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

Site updated at 2015-10-29 07:09:11 UTC

Browse source
This commit is contained in:
Paulus Schoutsen 2015-10-29 00:09:11 -07:00
parent 7412a60701
commit b260f2881e
362 changed files with 42053 additions and 256343 deletions
Download patch file Download diff file Expand all files Collapse all files

266
developers/add_new_platform.html
View file

@ -1,265 +1 @@
<!doctype html>
<!--[if lt IE 7]> <html class="no-js lt-ie9 lt-ie8 lt-ie7"> <![endif]-->
<!--[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="Paulus Schoutsen">
<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.html">
<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">
<meta property="og:url" content="https://home-assistant.io/developers/add_new_platform.html">
<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/home-assistant-logo-2164x2164.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='/images/favicon-192x192.png'> Home Assistant
</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>
<ul>
<li><a href='/getting-started/'>Installing Home Assistant</a></li>
<li><a href='/getting-started/configuration.html'>Configuration basics</a></li>
<li><a href='/getting-started/devices.html'>Adding devices</a></li>
<li><a href='/getting-started/presence-detection.html'>Presence detection</a></li>
<li><a href='/getting-started/automation.html'>Automation</a></li>
<li><a href='/cookbook'>Configuration cookbook</a></li>
</ul>
</li>
<li><a href='/components/'>Components</a></li>
<li>
<a href="/developers/">Developers</a>
<ul>
<li><a href="/developers/architecture.html">Architecture</a></li>
<li><a href="/developers/frontend.html">Frontend development</a></li>
<li><a href="/developers/creating_components.html">
Creating components
</a></li>
<li><a href="/developers/add_new_platform.html">
Adding platform support
</a></li>
<li><a href="/developers/api.html">API</a></li>
<li><a href="/developers/credits.html">Credits</a></li>
</ul>
</li>
<li><a href="/blog/">Blog</a></li>
<li><a href="/help/">Need help?</a></li>
</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 structured in core- and platform logic. This allows the same logic to be used for different platforms.</p>
<p>For example, the built-in <code>switch</code> component consists of the following files in <a href="https://github.com/balloob/home-assistant/tree/master/homeassistant/components/switch"><code>homeassistant/components/switch/</code></a>:</p>
<table>
<thead>
<tr>
<th> File </th>
<th> Description </th>
</tr>
</thead>
<tbody>
<tr>
<td> __init__.py </td>
<td> Contains the Switch core logic.</td>
</tr>
<tr>
<td> wemo.py </td>
<td> WeMo platform logic. Included if in config <code>platform=wemo</code>. </td>
</tr>
<tr>
<td> tellstick.py </td>
<td> Tellstick platform logic. Included if in config <code>platform=tellstick</code>. </td>
</tr>
</tbody>
</table>
<p>If you are planning to add support for a new type of device to an existing component, you can get away with only writing platform logic. Have a look at how the component works with other platforms and create a similar file for the platform that you would like to add.</p>
<h3><a class='title-link' name='interfacing-with-devices' href='#interfacing-with-devices'></a> Interfacing with devices</h3>
<p>One of the rules for Home Assistant is that platform logic should never interface directly with
devices but use a third-party Python 3 library to do so. This way Home Assistant is able to share
code with the Python community and we can keep the project maintainable.</p>
<p>Platforms can specify dependencies and requirements the same way as a component does. Please see
<a href="/developers/creating_components.html#dependencies">the component page</a> for more information.</p>
<h3><a class='title-link' name='creating-entities' href='#creating-entities'></a> Creating Entities</h3>
<p>Home Assistant will call a function with the following signature to initialize
your new platform. This function must exist in the platform module you create.</p>
<figure class='code'><figcaption><span></span></figcaption><div class="highlight"><table><tr><td class="gutter"><pre class="line-numbers"><span class='line-number'>1</span>
</pre></td><td class='code'><pre><code class='python'><span class='line'><span class="k">def</span> <span class="nf">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_devices</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></code></pre></td></tr></table></div></figure>
<p>In this function, your platform should create the appropriate entities and
register them with the Home Assistant core. Entities are Home Assistant&rsquo;s
representation of lights, switches, sensors, etc. and are derived from the
<a href="https://github.com/balloob/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 many more.</p>
<p>A list of entities can be registered with Home Assistant using the <em>add_devices</em>
function that is provided as an input to <em>setup_platform</em>. Once entities are
registered with with Home Assistant their updates will be provided to the core
and the core will have control over them. For more information on how Entities
can be customized, take a look at the <a href="https://github.com/balloob/home-assistant/blob/master/homeassistant/helpers/entity.py#L18">Entity Abstract
Class</a>.</p>
<h2><a class='title-link' name='allowing-your-platform-to-be-discovered' href='#allowing-your-platform-to-be-discovered'></a> Allowing your platform to be discovered</h2>
<p>Home Assistant has a discovery service running in the background to discover new devices. Whenever a new device is discovered, an <code>SERVICE_DISCOVERED</code> event will be fired with the found service and the information. The <code>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>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/balloob/netdisco">NetDisco</a>. This library is integrated using <a href="https://github.com/balloob/home-assistant/blob/dev/homeassistant/components/discovery.py">the <code>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/balloob/netdisco/tree/master/netdisco/discoverables">See the repository for examples of existing discoverables.</a></p>
<h3><a class='title-link' name='listening-to-service_discovered-events' href='#listening-to-service_discovered-events'></a> Listening to <code>SERVICE_DISCOVERED</code> events</h3>
<p>From your component, you will have to set up the listening for specific services. Below an example how one would listen for discovered Chromecasts:</p>
<figure class='code'><figcaption><span></span></figcaption><div class="highlight"><table><tr><td class="gutter"><pre class="line-numbers"><span class='line-number'>1</span>
<span class='line-number'>2</span>
<span class='line-number'>3</span>
<span class='line-number'>4</span>
<span class='line-number'>5</span>
<span class='line-number'>6</span>
<span class='line-number'>7</span>
<span class='line-number'>8</span>
<span class='line-number'>9</span>
<span class='line-number'>10</span>
<span class='line-number'>11</span>
</pre></td><td class='code'><pre><code class='python'><span class='line'><span class="kn">from</span> <span class="nn">homeassistant.loader</span> <span class="kn">import</span> <span class="n">get_component</span>
</span><span class='line'>
</span><span class='line'><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><span class='line'> <span class="n">discovery</span> <span class="o">=</span> <span class="n">get_component</span><span class="p">(</span><span class="s">&#39;discovery&#39;</span><span class="p">)</span>
</span><span class='line'>
</span><span class='line'> <span class="k">def</span> <span class="nf">chromecast_discovered</span><span class="p">(</span><span class="n">service</span><span class="p">,</span> <span class="n">info</span><span class="p">):</span>
</span><span class='line'> <span class="sd">&quot;&quot;&quot; Called when a Chromecast has been discovered. &quot;&quot;&quot;</span>
</span><span class='line'> <span class="k">print</span><span class="p">(</span><span class="s">&quot;Discovered a new Chromecast: {}&quot;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">info</span><span class="p">))</span>
</span><span class='line'>
</span><span class='line'> <span class="n">discovery</span><span class="o">.</span><span class="n">listen</span><span class="p">(</span>
</span><span class='line'> <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>
</span></code></pre></td></tr></table></div></figure>
<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>SERVICE_DISCOVERD</code> event. To do this you will have to update the <a href="https://github.com/balloob/home-assistant/blob/dev/homeassistant/components/discovery.py#L29"><code>SERVICE_HANDLERS</code></a> constant in <a href="https://github.com/balloob/home-assistant/blob/dev/homeassistant/components/discovery.py">the <code>discovery</code> component</a>.</p>
<p class='note warning'>
This option is currently limited to built-in components.
</p>
</article>
</div>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item">
<p class="copyright">
<span class="credit">Powered by <a href="http://octopress.org">Octopress</a>, <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>. Hosted by <a href='https://pages.github.com/'>GitHub</a> and served by <a href='https://cloudflare.com'>CloudFlare</a>.</span>
</p>
</div>
</div>
</div>
</footer>
<!--[if lt IE 7]>
<p class="chromeframe">You are using an <strong>outdated</strong> browser. Please <a href="http://browsehappy.com/">upgrade your browser</a> or <a href="http://www.google.com/chromeframe/?redirect=true">activate Google Chrome Frame</a> to improve your experience.</p>
<![endif]-->
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
g.src=('https:'==location.protocol?'//ssl':'//www')+'.google-analytics.com/ga.js';
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>
<script>document.location = '/developers/add_new_platform/';</script>

227
developers/add_new_platform/index.html Normal file
View file

@ -0,0 +1,227 @@
<!doctype html>
<!--[if lt IE 7]> <html class="no-js lt-ie9 lt-ie8 lt-ie7"> <![endif]-->
<!--[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="Paulus Schoutsen">
<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">
<meta property="og:url" content="https://home-assistant.io/developers/add_new_platform/">
<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/home-assistant-logo-2164x2164.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='/images/favicon-192x192.png'> Home Assistant
</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>
<ul>
<li><a href='/getting-started/'>Installing Home Assistant</a></li>
<li><a href='/getting-started/configuration/'>Configuration basics</a></li>
<li><a href='/getting-started/devices/'>Adding devices</a></li>
<li><a href='/getting-started/presence-detection/'>Presence detection</a></li>
<li><a href='/getting-started/automation/'>Automation</a></li>
<li><a href='/cookbook'>Configuration cookbook</a></li>
</ul>
</li>
<li><a href='/components/'>Components</a></li>
<li>
<a href="/developers/">Developers</a>
<ul>
<li><a href="/developers/architecture/">Architecture</a></li>
<li><a href="/developers/frontend/">Frontend development</a></li>
<li><a href="/developers/creating_components/">
Creating components
</a></li>
<li><a href="/developers/add_new_platform/">
Adding platform support
</a></li>
<li><a href="/developers/api/">API</a></li>
<li><a href="/developers/credits/">Credits</a></li>
</ul>
</li>
<li><a href="/blog/">Blog</a></li>
<li><a href="/help/">Need help?</a></li>
</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 structured in core- and platform logic. This allows the same logic to be used for different platforms.</p>
<p>For example, the built-in <code>switch</code> component consists of the following files in <a href="https://github.com/balloob/home-assistant/tree/master/homeassistant/components/switch"><code>homeassistant/components/switch/</code></a>:</p>
<table>
<thead>
<tr>
<th>File</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>__init__.py</td>
<td>Contains the Switch core logic.</td>
</tr>
<tr>
<td>wemo.py</td>
<td>WeMo platform logic. Included if in config <code>platform=wemo</code>.</td>
</tr>
<tr>
<td>tellstick.py</td>
<td>Tellstick platform logic. Included if in config <code>platform=tellstick</code>.</td>
</tr>
</tbody>
</table>
<p>If you are planning to add support for a new type of device to an existing component, you can get away with only writing platform logic. Have a look at how the component works with other platforms and create a similar file for the platform that you would like to add.</p>
<h3><a class="title-link" name="interfacing-with-devices" href="#interfacing-with-devices"></a> Interfacing with devices</h3>
<p>One of the rules for Home Assistant is that platform logic should never interface directly with devices but use a third-party Python 3 library to do so. This way Home Assistant is able to share code with the Python community and we can keep the project maintainable.</p>
<p>Platforms can specify dependencies and requirements the same way as a component does. Please see <a href="/developers/creating_components/#dependencies">the component page</a> for more information.</p>
<h3><a class="title-link" name="creating-entities" href="#creating-entities"></a> Creating Entities</h3>
<p>Home Assistant will call a function with the following signature to initialize your new platform. This function must exist in the platform module you create.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre><span class="keyword">def</span> <span class="function">setup_platform</span>(hass, config, add_devices, discovery_info=<span class="predefined-constant">None</span>)
</pre></div>
</div>
</div>
<p>In this function, your platform should create the appropriate entities and register them with the Home Assistant core. Entities are Home Assistant’s representation of lights, switches, sensors, etc. and are derived from the <a href="https://github.com/balloob/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 many more.</p>
<p>A list of entities can be registered with Home Assistant using the <em>add_devices</em> function that is provided as an input to <em>setup_platform</em>. Once entities are registered with with Home Assistant their updates will be provided to the core and the core will have control over them. For more information on how Entities can be customized, take a look at the <a href="https://github.com/balloob/home-assistant/blob/master/homeassistant/helpers/entity.py#L18">Entity Abstract Class</a>.</p>
<h2><a class="title-link" name="allowing-your-platform-to-be-discovered" href="#allowing-your-platform-to-be-discovered"></a> Allowing your platform to be discovered</h2>
<p>Home Assistant has a discovery service running in the background to discover new devices. Whenever a new device is discovered, an <code>SERVICE_DISCOVERED</code> event will be fired with the found service and the information. The <code>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>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/balloob/netdisco">NetDisco</a>. This library is integrated using <a href="https://github.com/balloob/home-assistant/blob/dev/homeassistant/components/discovery.py">the <code>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/balloob/netdisco/tree/master/netdisco/discoverables">See the repository for examples of existing discoverables.</a></p>
<h3><a class="title-link" name="listening-to-service_discovered-events" href="#listening-to-service_discovered-events"></a> Listening to <code>SERVICE_DISCOVERED</code> events</h3>
<p>From your component, you will have to set up the listening for specific services. Below an example how one would listen for discovered Chromecasts:</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre><span class="keyword">from</span> <span class="include">homeassistant.loader</span> <span class="keyword">import</span> <span class="include">get_component</span>
<span class="keyword">def</span> <span class="function">setup</span>(hass, config):
discovery = get_component(<span class="string"><span class="delimiter">'</span><span class="content">discovery</span><span class="delimiter">'</span></span>)
<span class="keyword">def</span> <span class="function">chromecast_discovered</span>(service, info):
<span class="docstring"><span class="delimiter">&quot;&quot;&quot;</span><span class="content"> Called when a Chromecast has been discovered. </span><span class="delimiter">&quot;&quot;&quot;</span></span>
print(<span class="string"><span class="delimiter">&quot;</span><span class="content">Discovered a new Chromecast: {}</span><span class="delimiter">&quot;</span></span>.format(info))
discovery.listen(
hass, discovery.services.GOOGLE_CAST, chromecast_discovered)
</pre></div>
</div>
</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>SERVICE_DISCOVERD</code> event. To do this you will have to update the <a href="https://github.com/balloob/home-assistant/blob/dev/homeassistant/components/discovery.py#L29"><code>SERVICE_HANDLERS</code></a> constant in <a href="https://github.com/balloob/home-assistant/blob/dev/homeassistant/components/discovery.py">the <code>discovery</code> component</a>.</p>
<p class="note warning">
This option is currently limited to built-in components.
</p>
</article>
</div>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item">
<p class="copyright">
<span class="credit">Powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>. Hosted by <a href='https://pages.github.com/'>GitHub</a> and served by <a href='https://cloudflare.com'>CloudFlare</a>.</span>
</p>
</div>
</div>
</div>
</footer>
<!--[if lt IE 7]>
<p class="chromeframe">You are using an <strong>outdated</strong> browser. Please <a href="http://browsehappy.com/">upgrade your browser</a> or <a href="http://www.google.com/chromeframe/?redirect=true">activate Google Chrome Frame</a> to improve your experience.</p>
<![endif]-->
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
g.src=('https:'==location.protocol?'//ssl':'//www')+'.google-analytics.com/ga.js';
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>

164
developers/api.html
View file

@ -1,163 +1 @@
<!doctype html>
<!--[if lt IE 7]> <html class="no-js lt-ie9 lt-ie8 lt-ie7"> <![endif]-->
<!--[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>Home Assistant API - Home Assistant</title>
<meta name="author" content="Paulus Schoutsen">
<meta name="description" content="Home Assistant API documentation">
<meta name="viewport" content="width=device-width">
<link rel="canonical" href="https://home-assistant.io/developers/api.html">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="Home Assistant API">
<meta property="og:site_name" content="Home Assistant">
<meta property="og:url" content="https://home-assistant.io/developers/api.html">
<meta property="og:type" content="website">
<meta property="og:description" content="Home Assistant API documentation">
<meta property="og:image" content="https://home-assistant.io/images/home-assistant-logo-2164x2164.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='/images/favicon-192x192.png'> Home Assistant
</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>
<ul>
<li><a href='/getting-started/'>Installing Home Assistant</a></li>
<li><a href='/getting-started/configuration.html'>Configuration basics</a></li>
<li><a href='/getting-started/devices.html'>Adding devices</a></li>
<li><a href='/getting-started/presence-detection.html'>Presence detection</a></li>
<li><a href='/getting-started/automation.html'>Automation</a></li>
<li><a href='/cookbook'>Configuration cookbook</a></li>
</ul>
</li>
<li><a href='/components/'>Components</a></li>
<li>
<a href="/developers/">Developers</a>
<ul>
<li><a href="/developers/architecture.html">Architecture</a></li>
<li><a href="/developers/frontend.html">Frontend development</a></li>
<li><a href="/developers/creating_components.html">
Creating components
</a></li>
<li><a href="/developers/add_new_platform.html">
Adding platform support
</a></li>
<li><a href="/developers/api.html">API</a></li>
<li><a href="/developers/credits.html">Credits</a></li>
</ul>
</li>
<li><a href="/blog/">Blog</a></li>
<li><a href="/help/">Need help?</a></li>
</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">
Home Assistant API
</h1>
</header>
<hr class="divider">
<p>Home Assistant is offering a RESTful API and a Python API for convenient access to
a Home Assistant instance over HTTP.</p>
<ul>
<li><a href="/developers/rest_api.html">Rest API</a></li>
<li><a href="/developers/python_api.html">Python API</a></li>
</ul>
</article>
</div>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item">
<p class="copyright">
<span class="credit">Powered by <a href="http://octopress.org">Octopress</a>, <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>. Hosted by <a href='https://pages.github.com/'>GitHub</a> and served by <a href='https://cloudflare.com'>CloudFlare</a>.</span>
</p>
</div>
</div>
</div>
</footer>
<!--[if lt IE 7]>
<p class="chromeframe">You are using an <strong>outdated</strong> browser. Please <a href="http://browsehappy.com/">upgrade your browser</a> or <a href="http://www.google.com/chromeframe/?redirect=true">activate Google Chrome Frame</a> to improve your experience.</p>
<![endif]-->
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
g.src=('https:'==location.protocol?'//ssl':'//www')+'.google-analytics.com/ga.js';
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>
<script>document.location = '/developers/api/';</script>

148
developers/api/index.html Normal file
View file

@ -0,0 +1,148 @@
<!doctype html>
<!--[if lt IE 7]> <html class="no-js lt-ie9 lt-ie8 lt-ie7"> <![endif]-->
<!--[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>Home Assistant API - Home Assistant</title>
<meta name="author" content="Paulus Schoutsen">
<meta name="description" content="Home Assistant API documentation">
<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="Home Assistant API">
<meta property="og:site_name" content="Home Assistant">
<meta property="og:url" content="https://home-assistant.io/developers/api/">
<meta property="og:type" content="website">
<meta property="og:description" content="Home Assistant API documentation">
<meta property="og:image" content="https://home-assistant.io/images/home-assistant-logo-2164x2164.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='/images/favicon-192x192.png'> Home Assistant
</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>
<ul>
<li><a href='/getting-started/'>Installing Home Assistant</a></li>
<li><a href='/getting-started/configuration/'>Configuration basics</a></li>
<li><a href='/getting-started/devices/'>Adding devices</a></li>
<li><a href='/getting-started/presence-detection/'>Presence detection</a></li>
<li><a href='/getting-started/automation/'>Automation</a></li>
<li><a href='/cookbook'>Configuration cookbook</a></li>
</ul>
</li>
<li><a href='/components/'>Components</a></li>
<li>
<a href="/developers/">Developers</a>
<ul>
<li><a href="/developers/architecture/">Architecture</a></li>
<li><a href="/developers/frontend/">Frontend development</a></li>
<li><a href="/developers/creating_components/">
Creating components
</a></li>
<li><a href="/developers/add_new_platform/">
Adding platform support
</a></li>
<li><a href="/developers/api/">API</a></li>
<li><a href="/developers/credits/">Credits</a></li>
</ul>
</li>
<li><a href="/blog/">Blog</a></li>
<li><a href="/help/">Need help?</a></li>
</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">
Home Assistant API
</h1>
</header>
<hr class="divider">
<p>Home Assistant is offering a RESTful API and a Python API for convenient access to <br />
a Home Assistant instance over HTTP.</p>
<ul>
<li><a href="/developers/rest_api/">Rest API</a></li>
<li><a href="/developers/python_api/">Python API</a></li>
</ul>
</article>
</div>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item">
<p class="copyright">
<span class="credit">Powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>. Hosted by <a href='https://pages.github.com/'>GitHub</a> and served by <a href='https://cloudflare.com'>CloudFlare</a>.</span>
</p>
</div>
</div>
</div>
</footer>
<!--[if lt IE 7]>
<p class="chromeframe">You are using an <strong>outdated</strong> browser. Please <a href="http://browsehappy.com/">upgrade your browser</a> or <a href="http://www.google.com/chromeframe/?redirect=true">activate Google Chrome Frame</a> to improve your experience.</p>
<![endif]-->
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
g.src=('https:'==location.protocol?'//ssl':'//www')+'.google-analytics.com/ga.js';
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>

301
developers/architecture.html
View file

@ -1,300 +1 @@
<!doctype html>
<!--[if lt IE 7]> <html class="no-js lt-ie9 lt-ie8 lt-ie7"> <![endif]-->
<!--[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="Paulus Schoutsen">
<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.html">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="Architecture">
<meta property="og:site_name" content="Home Assistant">
<meta property="og:url" content="https://home-assistant.io/developers/architecture.html">
<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/home-assistant-logo-2164x2164.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='/images/favicon-192x192.png'> Home Assistant
</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>
<ul>
<li><a href='/getting-started/'>Installing Home Assistant</a></li>
<li><a href='/getting-started/configuration.html'>Configuration basics</a></li>
<li><a href='/getting-started/devices.html'>Adding devices</a></li>
<li><a href='/getting-started/presence-detection.html'>Presence detection</a></li>
<li><a href='/getting-started/automation.html'>Automation</a></li>
<li><a href='/cookbook'>Configuration cookbook</a></li>
</ul>
</li>
<li><a href='/components/'>Components</a></li>
<li>
<a href="/developers/">Developers</a>
<ul>
<li><a href="/developers/architecture.html">Architecture</a></li>
<li><a href="/developers/frontend.html">Frontend development</a></li>
<li><a href="/developers/creating_components.html">
Creating components
</a></li>
<li><a href="/developers/add_new_platform.html">
Adding platform support
</a></li>
<li><a href="/developers/api.html">API</a></li>
<li><a href="/developers/credits.html">Credits</a></li>
</ul>
</li>
<li><a href="/blog/">Blog</a></li>
<li><a href="/help/">Need help?</a></li>
</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, it is important to get a clear overview of the home automation landscape as a whole. This will allow us to show how the different parts of Home Assistant fit in the picture. For a more lengthy discussion about what each part in this overview is responsible for, <a href='/blog/2014/12/26/home-control-home-automation-and-the-smart-home/'>check out our blog</a>. A tl;dr version of the blog:</p>
<ul>
<li>Home Control is responsible for collecting information on- and controlling devices.</li>
<li>Home Automation triggers commands based on user configurations.</li>
<li>Smart Home triggers commands based on previous behavior.</li>
</ul>
<p class='img'>
<a href='/images/architecture/home_automation_landscape.png'>
<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. It has four parts to make this possible:</p>
<ul>
<li>The <strong>Event Bus</strong> facilitates the firing and listening of events. This is the beating heart of Home Assistant.</li>
<li>The <strong>State Machine</strong> keeps track of the states of things. Fires a <code>state_changed</code> event when a state has been changed.</li>
<li>The <strong>Service Registry</strong> listens on the event bus for <code>call_service</code> events and allows other code to register services.</li>
<li>The <strong>Timer</strong> will send every 1 second a <code>time_changed</code> event on the event bus.</li>
</ul>
<p class='img'>
<a href='/images/architecture/ha_architecture.png'>
<img src='/images/architecture/ha_architecture.png' />
</a>
Overview of the Home Assistant core architecture
</p>
<p>Home Assistant can be extended by <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>We can differentiate between two different types of
components within Home Assistant.</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 will track devices within a specific domain and exist of a core part and platform specific logic. These components make their information available via the State Machine and the Event Bus. The component will also register services in the Service Registry to expose control of the devices.</p>
<p>For example, one of the built-in components is the <code>switch</code> component. This component is responsible for interaction with different types of switches.</p>
<p>If you are planning to add support for a new platform, please check out the <a href="/developers/add_new_platform.html">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 services that do common tasks within your house.</p>
<p>For example the <code>device_sun_light_trigger</code> component tracks the state of devices and the sun to make sure that the lights are turned on when it gets dark and there are people home. The component uses logic along the following lines:</p>
<pre><code>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>
<!-- comment to separate markdown blockquotes -->
<pre><code>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>
<!-- comment to separate markdown blockquotes -->
<pre><code>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>Another example of a home automation component can be found in <a href="https://github.com/balloob/home-assistant/blob/master/config/custom_components/example.py"><code>/config/custom_components/example.py</code></a>.</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 we see that we match pretty close to the initial sketched home automation overview. The smart home AI is not implemented yet and therefore omitted from the following picture.</p>
<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>Component&rsquo;s platform logic uses 3rd party Python libraries to communicate with the devices. This is done so that we can leverage great device libraries that are out there in the Python community.</p>
<h2><a class='title-link' name='multiple-connected-instances' href='#multiple-connected-instances'></a> Multiple connected instances</h2>
<p>Home Assistant supports running multiple synchronized instances using a master-slave model. Whenever <code>events.fire</code> or <code>states.set</code> is called on the salve it will forward it to the master. The master will replicate all events and changed states to its slaves.</p>
<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>
<figure class='code'><figcaption><span></span></figcaption><div class="highlight"><table><tr><td class="gutter"><pre class="line-numbers"><span class='line-number'>1</span>
<span class='line-number'>2</span>
<span class='line-number'>3</span>
<span class='line-number'>4</span>
<span class='line-number'>5</span>
<span class='line-number'>6</span>
<span class='line-number'>7</span>
<span class='line-number'>8</span>
<span class='line-number'>9</span>
<span class='line-number'>10</span>
<span class='line-number'>11</span>
<span class='line-number'>12</span>
<span class='line-number'>13</span>
<span class='line-number'>14</span>
<span class='line-number'>15</span>
</pre></td><td class='code'><pre><code class='python'><span class='line'><span class="kn">import</span> <span class="nn">homeassistant.remote</span> <span class="kn">as</span> <span class="nn">remote</span>
</span><span class='line'><span class="kn">import</span> <span class="nn">homeassistant.bootstrap</span> <span class="kn">as</span> <span class="nn">bootstrap</span>
</span><span class='line'>
</span><span class='line'><span class="c"># Location of the Master API: host, password, port.</span>
</span><span class='line'><span class="c"># Password and port are optional.</span>
</span><span class='line'><span class="n">remote_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">&quot;127.0.0.1&quot;</span><span class="p">,</span> <span class="s">&quot;password&quot;</span><span class="p">,</span> <span class="mi">8124</span><span class="p">)</span>
</span><span class='line'>
</span><span class='line'><span class="c"># Initialize slave</span>
</span><span class='line'><span class="n">hass</span> <span class="o">=</span> <span class="n">remote</span><span class="o">.</span><span class="n">HomeAssistant</span><span class="p">(</span><span class="n">remote_api</span><span class="p">)</span>
</span><span class='line'>
</span><span class='line'><span class="c"># To add an interface to the slave on localhost:8123</span>
</span><span class='line'><span class="n">bootstrap</span><span class="o">.</span><span class="n">setup_component</span><span class="p">(</span><span class="n">hass</span><span class="p">,</span> <span class="s">&#39;frontend&#39;</span><span class="p">)</span>
</span><span class='line'>
</span><span class='line'><span class="n">hass</span><span class="o">.</span><span class="n">start</span><span class="p">()</span>
</span><span class='line'><span class="n">hass</span><span class="o">.</span><span class="n">block_till_stopped</span><span class="p">()</span>
</span></code></pre></td></tr></table></div></figure>
<p class='note'>
Because each slave maintains its own ServiceRegistry it is possible to have multiple slaves respond to one service call.
</p>
</article>
</div>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item">
<p class="copyright">
<span class="credit">Powered by <a href="http://octopress.org">Octopress</a>, <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>. Hosted by <a href='https://pages.github.com/'>GitHub</a> and served by <a href='https://cloudflare.com'>CloudFlare</a>.</span>
</p>
</div>
</div>
</div>
</footer>
<!--[if lt IE 7]>
<p class="chromeframe">You are using an <strong>outdated</strong> browser. Please <a href="http://browsehappy.com/">upgrade your browser</a> or <a href="http://www.google.com/chromeframe/?redirect=true">activate Google Chrome Frame</a> to improve your experience.</p>
<![endif]-->
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
g.src=('https:'==location.protocol?'//ssl':'//www')+'.google-analytics.com/ga.js';
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>
<script>document.location = '/developers/architecture/';</script>

265
developers/architecture/index.html Normal file
View file

@ -0,0 +1,265 @@
<!doctype html>
<!--[if lt IE 7]> <html class="no-js lt-ie9 lt-ie8 lt-ie7"> <![endif]-->
<!--[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="Paulus Schoutsen">
<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">
<meta property="og:url" content="https://home-assistant.io/developers/architecture/">
<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/home-assistant-logo-2164x2164.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='/images/favicon-192x192.png'> Home Assistant
</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>
<ul>
<li><a href='/getting-started/'>Installing Home Assistant</a></li>
<li><a href='/getting-started/configuration/'>Configuration basics</a></li>
<li><a href='/getting-started/devices/'>Adding devices</a></li>
<li><a href='/getting-started/presence-detection/'>Presence detection</a></li>
<li><a href='/getting-started/automation/'>Automation</a></li>
<li><a href='/cookbook'>Configuration cookbook</a></li>
</ul>
</li>
<li><a href='/components/'>Components</a></li>
<li>
<a href="/developers/">Developers</a>
<ul>
<li><a href="/developers/architecture/">Architecture</a></li>
<li><a href="/developers/frontend/">Frontend development</a></li>
<li><a href="/developers/creating_components/">
Creating components
</a></li>
<li><a href="/developers/add_new_platform/">
Adding platform support
</a></li>
<li><a href="/developers/api/">API</a></li>
<li><a href="/developers/credits/">Credits</a></li>
</ul>
</li>
<li><a href="/blog/">Blog</a></li>
<li><a href="/help/">Need help?</a></li>
</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, it is important to get a clear overview of the home automation landscape as a whole. This will allow us to show how the different parts of Home Assistant fit in the picture. For a more lengthy discussion about what each part in this overview is responsible for, <a href="/blog/2014/12/26/home-control-home-automation-and-the-smart-home/">check out our blog</a>. A tl;dr version of the blog:</p>
<ul>
<li>Home Control is responsible for collecting information on- and controlling devices.</li>
<li>Home Automation triggers commands based on user configurations.</li>
<li>Smart Home triggers commands based on previous behavior.</li>
</ul>
<p class="img">
<a href="/images/architecture/home_automation_landscape.png">
<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. It has four parts to make this possible:</p>
<ul>
<li>The <strong>Event Bus</strong> facilitates the firing and listening of events. This is the beating heart of Home Assistant.</li>
<li>The <strong>State Machine</strong> keeps track of the states of things. Fires a <code>state_changed</code> event when a state has been changed.</li>
<li>The <strong>Service Registry</strong> listens on the event bus for <code>call_service</code> events and allows other code to register services.</li>
<li>The <strong>Timer</strong> will send every 1 second a <code>time_changed</code> event on the event bus.</li>
</ul>
<p class="img">
<a href="/images/architecture/ha_architecture.png">
<img src="/images/architecture/ha_architecture.png" />
</a>
Overview of the Home Assistant core architecture
</p>
<p>Home Assistant can be extended by <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>We can differentiate between two different types ofcomponents within Home Assistant.</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 will track devices within a specific domain and exist of a core part and platform specific logic. These components make their information available via the State Machine and the Event Bus. The component will also register services in the Service Registry to expose control of the devices.</p>
<p>For example, one of the built-in components is the <code>switch</code> component. This component is responsible for interaction with different types of switches.</p>
<p>If you are planning to add support for a new platform, please 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 services that do common tasks within your house.</p>
<p>For example the <a href="/components/device_sun_light_trigger/"><code>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 there are people home. The component uses logic along the following lines:</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre> 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
</pre></div>
</div>
</div>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre> In the event that the combined state of all tracked devices changes to 'Not Home':
If the lights are on:
Turn off the lights
</pre></div>
</div>
</div>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre> 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
</pre></div>
</div>
</div>
<p>An extended example of a home automation component can be found <a href="https://github.com/balloob/home-assistant/blob/master/config/custom_components/example.py">here</a>.</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 we see that we match pretty close to the initial sketched home automation overview. The smart home AI is not implemented yet and therefore omitted from the following picture.</p>
<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>Component’s platform logic uses 3rd party Python libraries to communicate with the devices. This is done so that we can leverage great device libraries that are out there in the Python community.</p>
<h2><a class="title-link" name="multiple-connected-instances" href="#multiple-connected-instances"></a> Multiple connected instances</h2>
<p>Home Assistant supports running multiple synchronized instances using a master-slave model. Whenever <code>events.fire</code> or <code>states.set</code> is called on the salve it will forward it to the master. The master will replicate all events and changed states to its slaves.</p>
<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="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre><span class="keyword">import</span> <span class="include">homeassistant.remote</span> <span class="keyword">as</span> remote
<span class="keyword">import</span> <span class="include">homeassistant.bootstrap</span> <span class="keyword">as</span> bootstrap
<span class="comment"># Location of the Master API: host, password, port.</span>
<span class="comment"># Password and port are optional.</span>
remote_api = remote.API(<span class="string"><span class="delimiter">&quot;</span><span class="content">127.0.0.1</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">password</span><span class="delimiter">&quot;</span></span>, <span class="integer">8124</span>)
<span class="comment"># Initialize slave</span>
hass = remote.HomeAssistant(remote_api)
<span class="comment"># To add an interface to the slave on localhost:8123</span>
bootstrap.setup_component(hass, <span class="string"><span class="delimiter">'</span><span class="content">frontend</span><span class="delimiter">'</span></span>)
hass.start()
hass.block_till_stopped()
</pre></div>
</div>
</div>
<p class="note">
Because each slave maintains its own ServiceRegistry it is possible to have multiple slaves respond to one service call.
</p>
</article>
</div>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item">
<p class="copyright">
<span class="credit">Powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>. Hosted by <a href='https://pages.github.com/'>GitHub</a> and served by <a href='https://cloudflare.com'>CloudFlare</a>.</span>
</p>
</div>
</div>
</div>
</footer>
<!--[if lt IE 7]>
<p class="chromeframe">You are using an <strong>outdated</strong> browser. Please <a href="http://browsehappy.com/">upgrade your browser</a> or <a href="http://www.google.com/chromeframe/?redirect=true">activate Google Chrome Frame</a> to improve your experience.</p>
<![endif]-->
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
g.src=('https:'==location.protocol?'//ssl':'//www')+'.google-analytics.com/ga.js';
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>

272
developers/creating_components.html
View file

@ -1,271 +1 @@
<!doctype html>
<!--[if lt IE 7]> <html class="no-js lt-ie9 lt-ie8 lt-ie7"> <![endif]-->
<!--[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="Paulus Schoutsen">
<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.html">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="Creating components">
<meta property="og:site_name" content="Home Assistant">
<meta property="og:url" content="https://home-assistant.io/developers/creating_components.html">
<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/home-assistant-logo-2164x2164.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='/images/favicon-192x192.png'> Home Assistant
</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>
<ul>
<li><a href='/getting-started/'>Installing Home Assistant</a></li>
<li><a href='/getting-started/configuration.html'>Configuration basics</a></li>
<li><a href='/getting-started/devices.html'>Adding devices</a></li>
<li><a href='/getting-started/presence-detection.html'>Presence detection</a></li>
<li><a href='/getting-started/automation.html'>Automation</a></li>
<li><a href='/cookbook'>Configuration cookbook</a></li>
</ul>
</li>
<li><a href='/components/'>Components</a></li>
<li>
<a href="/developers/">Developers</a>
<ul>
<li><a href="/developers/architecture.html">Architecture</a></li>
<li><a href="/developers/frontend.html">Frontend development</a></li>
<li><a href="/developers/creating_components.html">
Creating components
</a></li>
<li><a href="/developers/add_new_platform.html">
Adding platform support
</a></li>
<li><a href="/developers/api.html">API</a></li>
<li><a href="/developers/credits.html">Credits</a></li>
</ul>
</li>
<li><a href="/blog/">Blog</a></li>
<li><a href="/help/">Need help?</a></li>
</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>Home Assistant offers <a href="/components/">built-in components</a> but it is easy to built your own. If you are the kind of person that likes to learn from code rather then guide then head over to the <a href="https://github.com/balloob/home-assistant/tree/master/config/custom_components"><code>config/custom_components</code></a> folder in the repository for two example components.</p>
<p>The first is <a href="https://github.com/balloob/home-assistant/blob/master/config/custom_components/hello_world.py">hello_world.py</a>, which is the classic Hello World example for Home Assistant. The second one is <a href="https://github.com/balloob/home-assistant/blob/master/config/custom_components/example.py">example.py</a> which showcases various ways you can tap into Home Assistant to be notified when certain events occur.</p>
<p>If you want to load these components in Home Assistant, add the following lines to your <code>configuration.yaml</code> file:</p>
<figure class='code'><figcaption><span></span></figcaption><div class="highlight"><table><tr><td class="gutter"><pre class="line-numbers"><span class='line-number'>1</span>
<span class='line-number'>2</span>
<span class='line-number'>3</span>
<span class='line-number'>4</span>
</pre></td><td class='code'><pre><code class='yaml'><span class='line'><span class="l-Scalar-Plain">hello_world</span><span class="p-Indicator">:</span>
</span><span class='line'>
</span><span class='line'><span class="l-Scalar-Plain">example</span><span class="p-Indicator">:</span>
</span><span class='line'> <span class="l-Scalar-Plain">target</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">TARGET_ENTITY</span>
</span></code></pre></td></tr></table></div></figure>
<p><code>TARGET_ENTITY</code> should be one of your devices that can be turned on and off, ie a light or a switch. Example value could be <code>light.Ceiling</code> or <code>switch.AC</code> (if you have these devices with those names).</p>
<h2><a class='title-link' name='loading-components' href='#loading-components'></a> Loading components</h2>
<p>A component will be loaded on start if a section (ie. <code>[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>&lt;config directory>/custom_components/&lt;component name></code></li>
<li><code>homeassistant/components/&lt;component name></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. This 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 &#8211;config argument: <code>python3 homeassistant --config /YOUR/CONFIG/PATH/</code>.
</p>
<h2><a class='title-link' name='dependencies' href='#dependencies'></a> Dependencies</h2>
<p>Home Assistant allows components and platforms to specify their dependencies and requirements using the variables <code>DEPENDENCIES</code> and <code>REQUIREMENTS</code>. Both are lists that contain strings.</p>
<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>
<p>Requirements are Python libraries that you would normally install using <code>pip</code>. Each entry in a requirement list is a pip compatible string. For example, the media player Cast platform depends on the Python package PyChromecast thus <code>REQUIREMENTS = ['pychromecast==0.6.12']</code>. If Home Assistant is unable to install the package or verify it is installed, the component will fail to
load.</p>
<h2><a class='title-link' name='initializing-components' href='#initializing-components'></a> Initializing components</h2>
<p>After loading, the bootstrapper will call <code>setup(hass, config)</code> method on the component to initialize it. The following parameters are passed in:</p>
<table>
<thead>
<tr>
<th> Parameter </th>
<th> Description </th>
</tr>
</thead>
<tbody>
<tr>
<td> <code>hass</code> </td>
<td> The Home Assistant object. Call its methods to track time, register services, listen for events or track states: <a href="https://github.com/balloob/home-assistant/blob/dev/homeassistant/core.py#L55">Overview of available methods.</a> </td>
</tr>
<tr>
<td> <code>config</code> </td>
<td> A dict containing the configuration. The keys of the config-dict are component names and the value is another dict with the component configuration.: <a href="https://github.com/balloob/home-assistant/blob/dev/homeassistant/core.py#L687">Details</a> </td>
</tr>
</tbody>
</table>
<h3><a class='title-link' name='guidance-on-using-the-home-assistant-object' href='#guidance-on-using-the-home-assistant-object'></a> Guidance on using the Home Assistant object</h3>
<p>The Home Assistant object contains three objects to help you interact with the system.</p>
<table>
<thead>
<tr>
<th> Object </th>
<th> Description </th>
</tr>
</thead>
<tbody>
<tr>
<td> <code>hass.states</code> </td>
<td> This is the StateMachine. It allows you to set states and track when they are changed. <a href="https://github.com/balloob/home-assistant/blob/dev/homeassistant/core.py#L434">See available methods</a>. </td>
</tr>
<tr>
<td> <code>hass.bus</code> </td>
<td> This is the EventBus. It allows you to trigger and listen for events.<br><a href="https://github.com/balloob/home-assistant/blob/dev/homeassistant/core.py#L229">See available methods</a>. </td>
</tr>
<tr>
<td> <code>hass.services</code> </td>
<td> This is the ServiceRegistry. It allows you to register services.<br><a href="https://github.com/balloob/home-assistant/blob/dev/homeassistant/core.py#L568">See available methods</a>. </td>
</tr>
</tbody>
</table>
<h3><a class='title-link' name='example-on-using-the-configuration-parameter' href='#example-on-using-the-configuration-parameter'></a> Example on using the configuration parameter</h3>
<p>If your configuration file contains the following lines:</p>
<figure class='code'><figcaption><span></span></figcaption><div class="highlight"><table><tr><td class="gutter"><pre class="line-numbers"><span class='line-number'>1</span>
<span class='line-number'>2</span>
</pre></td><td class='code'><pre><code class='yaml'><span class='line'><span class="l-Scalar-Plain">example</span><span class="p-Indicator">:</span>
</span><span class='line'> <span class="l-Scalar-Plain">host</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">paulusschoutsen.nl</span>
</span></code></pre></td></tr></table></div></figure>
<p>Then in the setup method of your component you will be able to refer to <code>config['example']['host']</code> to get the value <code>paulusschoutsen.nl</code>.</p>
</article>
</div>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item">
<p class="copyright">
<span class="credit">Powered by <a href="http://octopress.org">Octopress</a>, <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>. Hosted by <a href='https://pages.github.com/'>GitHub</a> and served by <a href='https://cloudflare.com'>CloudFlare</a>.</span>
</p>
</div>
</div>
</div>
</footer>
<!--[if lt IE 7]>
<p class="chromeframe">You are using an <strong>outdated</strong> browser. Please <a href="http://browsehappy.com/">upgrade your browser</a> or <a href="http://www.google.com/chromeframe/?redirect=true">activate Google Chrome Frame</a> to improve your experience.</p>
<![endif]-->
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
g.src=('https:'==location.protocol?'//ssl':'//www')+'.google-analytics.com/ga.js';
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>
<script>document.location = '/developers/creating_components/';</script>

238
developers/creating_components/index.html Normal file
View file

@ -0,0 +1,238 @@
<!doctype html>
<!--[if lt IE 7]> <html class="no-js lt-ie9 lt-ie8 lt-ie7"> <![endif]-->
<!--[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="Paulus Schoutsen">
<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">
<meta property="og:url" content="https://home-assistant.io/developers/creating_components/">
<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/home-assistant-logo-2164x2164.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='/images/favicon-192x192.png'> Home Assistant
</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>
<ul>
<li><a href='/getting-started/'>Installing Home Assistant</a></li>
<li><a href='/getting-started/configuration/'>Configuration basics</a></li>
<li><a href='/getting-started/devices/'>Adding devices</a></li>
<li><a href='/getting-started/presence-detection/'>Presence detection</a></li>
<li><a href='/getting-started/automation/'>Automation</a></li>
<li><a href='/cookbook'>Configuration cookbook</a></li>
</ul>
</li>
<li><a href='/components/'>Components</a></li>
<li>
<a href="/developers/">Developers</a>
<ul>
<li><a href="/developers/architecture/">Architecture</a></li>
<li><a href="/developers/frontend/">Frontend development</a></li>
<li><a href="/developers/creating_components/">
Creating components
</a></li>
<li><a href="/developers/add_new_platform/">
Adding platform support
</a></li>
<li><a href="/developers/api/">API</a></li>
<li><a href="/developers/credits/">Credits</a></li>
</ul>
</li>
<li><a href="/blog/">Blog</a></li>
<li><a href="/help/">Need help?</a></li>
</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>Home Assistant offers <a href="/components/">built-in components</a> but it is easy to built your own. If you are the kind of person that likes to learn from code rather then guide then head over to the <a href="https://github.com/balloob/home-assistant/tree/master/config/custom_components"><code>config/custom_components</code></a> folder in the repository for two example components.</p>
<p>The first is <a href="https://github.com/balloob/home-assistant/blob/master/config/custom_components/hello_world.py">hello_world.py</a>, which is the classic Hello World example for Home Assistant. The second one is <a href="https://github.com/balloob/home-assistant/blob/master/config/custom_components/example.py">example.py</a> which showcases various ways you can tap into Home Assistant to be notified when certain events occur.</p>
<p>If you want to load these components in Home Assistant, add the following lines to your <code>configuration.yaml</code> file:</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre><span class="key">hello_world</span>:
<span class="key">example</span>:
<span class="key">target</span>: <span class="string"><span class="content">TARGET_ENTITY</span></span>
</pre></div>
</div>
</div>
<p><code>TARGET_ENTITY</code> should be one of your devices that can be turned on and off, ie a light or a switch. Example value could be <code>light.Ceiling</code> or <code>switch.AC</code> (if you have these devices with those names).</p>
<h2><a class="title-link" name="loading-components" href="#loading-components"></a> Loading components</h2>
<p>A component will be loaded on start if a section (ie. <code>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>&lt;config directory&gt;/custom_components/&lt;component name&gt;</code></li>
<li><code>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. This 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>
<h2><a class="title-link" name="dependencies" href="#dependencies"></a> Dependencies</h2>
<p>Home Assistant allows components and platforms to specify their dependencies and requirements using the variables <code>DEPENDENCIES</code> and <code>REQUIREMENTS</code>. Both are lists that contain strings.</p>
<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>
<p>Requirements are Python libraries that you would normally install using <code>pip</code>. Each entry in a requirement list is a pip compatible string. For example, the media player Cast platform depends on the Python package PyChromecast thus <code>REQUIREMENTS = ['pychromecast==0.6.12']</code>. If Home Assistant is unable to install the package or verify it is installed, the component will fail to load.</p>
<h2><a class="title-link" name="initializing-components" href="#initializing-components"></a> Initializing components</h2>
<p>After loading, the bootstrapper will call <code>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> <code>hass</code>: the Home Assistant instance</h3>
<p>The Home Assistant instace contains three objects to help you interact with the system.</p>
<table>
<thead>
<tr>
<th>Object</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>hass.config</code></td>
<td>This is the core configuration of Home Assistant exposing location, temperature preferences and config directory path. <a href="https://github.com/balloob/home-assistant/blob/dev/homeassistant/core.py#L687">Details</a></td>
</tr>
<tr>
<td><code>hass.states</code></td>
<td>This is the StateMachine. It allows you to set states and track when they are changed. <a href="https://github.com/balloob/home-assistant/blob/dev/homeassistant/core.py#L434">See available methods</a>.</td>
</tr>
<tr>
<td><code>hass.bus</code></td>
<td>This is the EventBus. It allows you to trigger and listen for events.<br /><a href="https://github.com/balloob/home-assistant/blob/dev/homeassistant/core.py#L229">See available methods</a>.</td>
</tr>
<tr>
<td><code>hass.services</code></td>
<td>This is the ServiceRegistry. It allows you to register services.<br /><a href="https://github.com/balloob/home-assistant/blob/dev/homeassistant/core.py#L568">See available methods</a>.</td>
</tr>
</tbody>
</table>
<h3><a class="title-link" name="config-user-given-configuration" href="#config-user-given-configuration"></a> <code>config</code>: User given configuration.</h3>
<p>The <code>config</code> paramter is a dictionary containing the user supplied configuration. The keys of the dictionary are the component names and the value is another dictionary with the component configuration.</p>
<p>If your configuration file contains the following lines:</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre><span class="key">example</span>:
<span class="key">host</span>: <span class="string"><span class="content">paulusschoutsen.nl</span></span>
</pre></div>
</div>
</div>
<p>Then in the setup method of your component you will be able to refer to <code>config['example']['host']</code> to get the value <code>paulusschoutsen.nl</code>.</p>
<h2><a class="title-link" name="responding-to-events" href="#responding-to-events"></a> Responding to events</h2>
<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/balloob/home-assistant/blob/dev/homeassistant/helpers/event.py">helper methods</a>. Examples are <code>track_state_change</code>, <code>track_point_in_time</code>, <code>track_time_change</code>.</p>
</article>
</div>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item">
<p class="copyright">
<span class="credit">Powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>. Hosted by <a href='https://pages.github.com/'>GitHub</a> and served by <a href='https://cloudflare.com'>CloudFlare</a>.</span>
</p>
</div>
</div>
</div>
</footer>
<!--[if lt IE 7]>
<p class="chromeframe">You are using an <strong>outdated</strong> browser. Please <a href="http://browsehappy.com/">upgrade your browser</a> or <a href="http://www.google.com/chromeframe/?redirect=true">activate Google Chrome Frame</a> to improve your experience.</p>
<![endif]-->
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
g.src=('https:'==location.protocol?'//ssl':'//www')+'.google-analytics.com/ga.js';
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>

224
developers/credits.html
View file

@ -1,223 +1 @@
<!doctype html>
<!--[if lt IE 7]> <html class="no-js lt-ie9 lt-ie8 lt-ie7"> <![endif]-->
<!--[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="Paulus Schoutsen">
<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.html">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="Credits">
<meta property="og:site_name" content="Home Assistant">
<meta property="og:url" content="https://home-assistant.io/developers/credits.html">
<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/home-assistant-logo-2164x2164.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='/images/favicon-192x192.png'> Home Assistant
</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>
<ul>
<li><a href='/getting-started/'>Installing Home Assistant</a></li>
<li><a href='/getting-started/configuration.html'>Configuration basics</a></li>
<li><a href='/getting-started/devices.html'>Adding devices</a></li>
<li><a href='/getting-started/presence-detection.html'>Presence detection</a></li>
<li><a href='/getting-started/automation.html'>Automation</a></li>
<li><a href='/cookbook'>Configuration cookbook</a></li>
</ul>
</li>
<li><a href='/components/'>Components</a></li>
<li>
<a href="/developers/">Developers</a>
<ul>
<li><a href="/developers/architecture.html">Architecture</a></li>
<li><a href="/developers/frontend.html">Frontend development</a></li>
<li><a href="/developers/creating_components.html">
Creating components
</a></li>
<li><a href="/developers/add_new_platform.html">
Adding platform support
</a></li>
<li><a href="/developers/api.html">API</a></li>
<li><a href="/developers/credits.html">Credits</a></li>
</ul>
</li>
<li><a href="/blog/">Blog</a></li>
<li><a href="/help/">Need help?</a></li>
</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.</p>
<h2>Author</h2>
<ul>
<li><a href="https://github.com/balloob">Paulus Schoutsen</a></li>
</ul>
<h2>Contributors</h2>
<p>(in alphabetical order)</p>
<ul>
<li><a href="https://github.com/adrienbrault">Adrien Brault</a></li>
<li><a href="https://github.com/andythigpen">andythigpen</a></li>
<li><a href="https://github.com/trainman419">Austin</a></li>
<li><a href="https://github.com/Azelphur">Azelphur</a></li>
<li><a href="https://github.com/badele">Bruno Adele</a></li>
<li><a href="https://github.com/CCOSTAN">Carlo Costanzo</a></li>
<li><a href="https://github.com/chrisvis">Chris Mulder</a></li>
<li><a href="https://github.com/danielhiversen">Daniel Iversen</a></li>
<li><a href="https://github.com/Dutchy-">Edwin Smulders</a></li>
<li><a href="https://github.com/ettisan">ettisan</a></li>
<li><a href="https://github.com/fabaff">Fabian Affolter</a></li>
<li><a href="https://github.com/fbradyirl">Finbarr Brady</a></li>
<li><a href="https://github.com/kangaroo">Geoff Norton</a></li>
<li><a href="https://github.com/gottsman">gottsman</a></li>
<li><a href="https://github.com/pavoni">Greg Dowling</a></li>
<li><a href="https://github.com/gbarba">Guillem Barba</a></li>
<li><a href="https://github.com/Gyran">Gustav Ahlberg</a></li>
<li><a href="https://github.com/heathbar">Heathbar</a></li>
<li><a href="https://github.com/issackelly">Issac Kelly</a></li>
<li><a href="https://github.com/jamespcole">James Cole</a></li>
<li><a href="https://github.com/Qrtn">Jeffrey Tang</a></li>
<li><a href="https://github.com/SEJeff">Jeff Schroeder</a></li>
<li><a href="https://github.com/loghound">John McLaughlin</a></li>
<li><a href="https://github.com/Jaidan">John Williams</a></li>
<li><a href="https://github.com/maddox">Jon Maddox</a></li>
<li><a href="https://github.com/eagleamon">Joseph Piron</a></li>
<li><a href="https://github.com/jd">Julien Danjou</a></li>
<li><a href="https://github.com/kixam">kixam</a></li>
<li><a href="https://github.com/MagnusKnutas">Magnus Knutas</a></li>
<li><a href="https://github.com/MakeMeASandwich">MakeMeASandwich</a></li>
<li><a href="https://github.com/fingon">Markus Stenberg</a></li>
<li><a href="https://github.com/michaelarnauts">Michael Arnauts</a></li>
<li><a href="https://github.com/auchter">Michael Auchter</a></li>
<li><a href="https://github.com/Zyell">Michael Gilbert</a></li>
<li><a href="https://github.com/miniconfig">miniconfig</a></li>
<li><a href="https://github.com/nkgilley">Nolan Gilley</a></li>
<li><a href="https://github.com/bachp">Pascal Bach</a></li>
<li><a href="https://github.com/persandstrom">Per Sandström</a></li>
<li><a href="https://github.com/Piratonym">Piratonym</a></li>
<li><a href="https://github.com/mikegrb">Rev Michael Greb</a></li>
<li><a href="https://github.com/rhooper">rhooper</a></li>
<li><a href="https://github.com/rkabadi">rkabadi</a></li>
<li><a href="https://github.com/rmkraus">Ryan Kraus</a></li>
<li><a href="https://github.com/sfam">sfam</a></li>
<li><a href="https://github.com/stefan-jonasson">Stefan Jonasson</a></li>
<li><a href="https://github.com/theolind">Theodor Lindquist</a></li>
<li><a href="https://github.com/toddeye">toddeye</a></li>
<li><a href="https://github.com/tomduijf">Tom Duijf</a></li>
<li><a href="https://github.com/vitorespindola">vitorespindola</a></li>
<li><a href="https://github.com/wind-rider">wind-rider</a></li>
</ul>
<p>This page is irregularly updated. As a base we use the Github <a href="https://github.com/balloob/home-assistant/graphs/contributors">contributors overview</a> of the Home Assistant git repository and the <a href="https://github.com/balloob/home-assistant.io/graphs/contributors">overview</a> for <a href="https://home-assistant.io">home-assistant.io</a>. If you think that you are missing, please let us know or add yourself.</p>
</article>
</div>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item">
<p class="copyright">
<span class="credit">Powered by <a href="http://octopress.org">Octopress</a>, <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>. Hosted by <a href='https://pages.github.com/'>GitHub</a> and served by <a href='https://cloudflare.com'>CloudFlare</a>.</span>
</p>
</div>
</div>
</div>
</footer>
<!--[if lt IE 7]>
<p class="chromeframe">You are using an <strong>outdated</strong> browser. Please <a href="http://browsehappy.com/">upgrade your browser</a> or <a href="http://www.google.com/chromeframe/?redirect=true">activate Google Chrome Frame</a> to improve your experience.</p>
<![endif]-->
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
g.src=('https:'==location.protocol?'//ssl':'//www')+'.google-analytics.com/ga.js';
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>
<script>document.location = '/developers/credits/';</script>

207
developers/credits/index.html Normal file
View file

@ -0,0 +1,207 @@
<!doctype html>
<!--[if lt IE 7]> <html class="no-js lt-ie9 lt-ie8 lt-ie7"> <![endif]-->
<!--[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="Paulus Schoutsen">
<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">
<meta property="og:url" content="https://home-assistant.io/developers/credits/">
<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/home-assistant-logo-2164x2164.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='/images/favicon-192x192.png'> Home Assistant
</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>
<ul>
<li><a href='/getting-started/'>Installing Home Assistant</a></li>
<li><a href='/getting-started/configuration/'>Configuration basics</a></li>
<li><a href='/getting-started/devices/'>Adding devices</a></li>
<li><a href='/getting-started/presence-detection/'>Presence detection</a></li>
<li><a href='/getting-started/automation/'>Automation</a></li>
<li><a href='/cookbook'>Configuration cookbook</a></li>
</ul>
</li>
<li><a href='/components/'>Components</a></li>
<li>
<a href="/developers/">Developers</a>
<ul>
<li><a href="/developers/architecture/">Architecture</a></li>
<li><a href="/developers/frontend/">Frontend development</a></li>
<li><a href="/developers/creating_components/">
Creating components
</a></li>
<li><a href="/developers/add_new_platform/">
Adding platform support
</a></li>
<li><a href="/developers/api/">API</a></li>
<li><a href="/developers/credits/">Credits</a></li>
</ul>
</li>
<li><a href="/blog/">Blog</a></li>
<li><a href="/help/">Need help?</a></li>
</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.</p>
<h2>Author</h2>
<ul>
<li><a href="https://github.com/balloob">Paulus Schoutsen</a></li>
</ul>
<h2>Contributors</h2>
<p>(in alphabetical order)</p>
<ul>
<li><a href="https://github.com/adrienbrault">Adrien Brault</a></li>
<li><a href="https://github.com/andythigpen">andythigpen</a></li>
<li><a href="https://github.com/trainman419">Austin</a></li>
<li><a href="https://github.com/Azelphur">Azelphur</a></li>
<li><a href="https://github.com/badele">Bruno Adele</a></li>
<li><a href="https://github.com/CCOSTAN">Carlo Costanzo</a></li>
<li><a href="https://github.com/chrisvis">Chris Mulder</a></li>
<li><a href="https://github.com/danielhiversen">Daniel Iversen</a></li>
<li><a href="https://github.com/Dutchy-">Edwin Smulders</a></li>
<li><a href="https://github.com/ettisan">ettisan</a></li>
<li><a href="https://github.com/fabaff">Fabian Affolter</a></li>
<li><a href="https://github.com/fbradyirl">Finbarr Brady</a></li>
<li><a href="https://github.com/kangaroo">Geoff Norton</a></li>
<li><a href="https://github.com/gottsman">gottsman</a></li>
<li><a href="https://github.com/pavoni">Greg Dowling</a></li>
<li><a href="https://github.com/gbarba">Guillem Barba</a></li>
<li><a href="https://github.com/Gyran">Gustav Ahlberg</a></li>
<li><a href="https://github.com/heathbar">Heathbar</a></li>
<li><a href="https://github.com/issackelly">Issac Kelly</a></li>
<li><a href="https://github.com/jamespcole">James Cole</a></li>
<li><a href="https://github.com/Qrtn">Jeffrey Tang</a></li>
<li><a href="https://github.com/SEJeff">Jeff Schroeder</a></li>
<li><a href="https://github.com/loghound">John McLaughlin</a></li>
<li><a href="https://github.com/Jaidan">John Williams</a></li>
<li><a href="https://github.com/maddox">Jon Maddox</a></li>
<li><a href="https://github.com/eagleamon">Joseph Piron</a></li>
<li><a href="https://github.com/jd">Julien Danjou</a></li>
<li><a href="https://github.com/kixam">kixam</a></li>
<li><a href="https://github.com/MagnusKnutas">Magnus Knutas</a></li>
<li><a href="https://github.com/MakeMeASandwich">MakeMeASandwich</a></li>
<li><a href="https://github.com/fingon">Markus Stenberg</a></li>
<li><a href="https://github.com/michaelarnauts">Michael Arnauts</a></li>
<li><a href="https://github.com/auchter">Michael Auchter</a></li>
<li><a href="https://github.com/Zyell">Michael Gilbert</a></li>
<li><a href="https://github.com/miniconfig">miniconfig</a></li>
<li><a href="https://github.com/nkgilley">Nolan Gilley</a></li>
<li><a href="https://github.com/bachp">Pascal Bach</a></li>
<li><a href="https://github.com/persandstrom">Per Sandström</a></li>
<li><a href="https://github.com/Piratonym">Piratonym</a></li>
<li><a href="https://github.com/mikegrb">Rev Michael Greb</a></li>
<li><a href="https://github.com/rhooper">rhooper</a></li>
<li><a href="https://github.com/rkabadi">rkabadi</a></li>
<li><a href="https://github.com/rmkraus">Ryan Kraus</a></li>
<li><a href="https://github.com/sfam">sfam</a></li>
<li><a href="https://github.com/stefan-jonasson">Stefan Jonasson</a></li>
<li><a href="https://github.com/theolind">Theodor Lindquist</a></li>
<li><a href="https://github.com/toddeye">toddeye</a></li>
<li><a href="https://github.com/tomduijf">Tom Duijf</a></li>
<li><a href="https://github.com/vitorespindola">vitorespindola</a></li>
<li><a href="https://github.com/wind-rider">wind-rider</a></li>
</ul>
<p>This page is irregularly updated. As a base we use the Github <a href="https://github.com/balloob/home-assistant/graphs/contributors">contributors overview</a> of the Home Assistant git repository and the <a href="https://github.com/balloob/home-assistant.io/graphs/contributors">overview</a> for <a href="https://home-assistant.io">home-assistant.io</a>. If you think that you are missing, please let us know or add yourself.</p>
</article>
</div>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item">
<p class="copyright">
<span class="credit">Powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>. Hosted by <a href='https://pages.github.com/'>GitHub</a> and served by <a href='https://cloudflare.com'>CloudFlare</a>.</span>
</p>
</div>
</div>
</div>
</footer>
<!--[if lt IE 7]>
<p class="chromeframe">You are using an <strong>outdated</strong> browser. Please <a href="http://browsehappy.com/">upgrade your browser</a> or <a href="http://www.google.com/chromeframe/?redirect=true">activate Google Chrome Frame</a> to improve your experience.</p>
<![endif]-->
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
g.src=('https:'==location.protocol?'//ssl':'//www')+'.google-analytics.com/ga.js';
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>

288
developers/frontend.html
View file

@ -1,287 +1 @@
<!doctype html>
<!--[if lt IE 7]> <html class="no-js lt-ie9 lt-ie8 lt-ie7"> <![endif]-->
<!--[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="Paulus Schoutsen">
<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.html">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="Frontend development">
<meta property="og:site_name" content="Home Assistant">
<meta property="og:url" content="https://home-assistant.io/developers/frontend.html">
<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/home-assistant-logo-2164x2164.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='/images/favicon-192x192.png'> Home Assistant
</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>
<ul>
<li><a href='/getting-started/'>Installing Home Assistant</a></li>
<li><a href='/getting-started/configuration.html'>Configuration basics</a></li>
<li><a href='/getting-started/devices.html'>Adding devices</a></li>
<li><a href='/getting-started/presence-detection.html'>Presence detection</a></li>
<li><a href='/getting-started/automation.html'>Automation</a></li>
<li><a href='/cookbook'>Configuration cookbook</a></li>
</ul>
</li>
<li><a href='/components/'>Components</a></li>
<li>
<a href="/developers/">Developers</a>
<ul>
<li><a href="/developers/architecture.html">Architecture</a></li>
<li><a href="/developers/frontend.html">Frontend development</a></li>
<li><a href="/developers/creating_components.html">
Creating components
</a></li>
<li><a href="/developers/add_new_platform.html">
Adding platform support
</a></li>
<li><a href="/developers/api.html">API</a></li>
<li><a href="/developers/credits.html">Credits</a></li>
</ul>
</li>
<li><a href="/blog/">Blog</a></li>
<li><a href="/help/">Need help?</a></li>
</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 uses <a href="https://www.polymer-project.org/">Polymer</a> for the UI and <a href="http://optimizely.github.io/nuclear-js/">NuclearJS</a> for all data management.</p>
<ul>
<li>Polymer allows building encapsulated custom HTML elements.<br/>
<a href="https://github.com/balloob/home-assistant-polymer">Home-Assistant-Polymer source code on GitHub.</a></li>
<li>NuclearJS is a reactive flux built with ImmutableJS data structures.<br/>
<a href="https://github.com/balloob/home-assistant-js">Home-Assistant-JS source code on GitHub.</a></li>
</ul>
<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>
<h1><a class='title-link' name='turning-on-development-mode' href='#turning-on-development-mode'></a> Turning on development mode</h1>
<p>Home Assistant will by default serve the compiled version of the frontend. To change it so that each component and JavaScript are served separately, update your <code>configuration.yaml</code> to have these lines:</p>
<figure class='code'><figcaption><span></span></figcaption><div class="highlight"><table><tr><td class="gutter"><pre class="line-numbers"><span class='line-number'>1</span>
<span class='line-number'>2</span>
</pre></td><td class='code'><pre><code class='yaml'><span class='line'><span class="l-Scalar-Plain">http</span><span class="p-Indicator">:</span>
</span><span class='line'> <span class="l-Scalar-Plain">development</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">1</span>
</span></code></pre></td></tr></table></div></figure>
<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 will have to trigger this manually by running from the
command line:</p>
<figure class='code'><figcaption><span></span></figcaption><div class="highlight"><table><tr><td class="gutter"><pre class="line-numbers"><span class='line-number'>1</span>
</pre></td><td class='code'><pre><code class='bash'><span class='line'>git submodule update --init
</span></code></pre></td></tr></table></div></figure>
<p>After checking out the frontend code, you will have to install the frontend dependencies. Firing off
a build of the frontend by running <code>script/build_frontend</code> will ensure they get installed.</p>
<p>Once this is done, you can start editting the webcomponents in the folder
<code>homeassistant/components/frontend/www_static/home-assistant-polymer/src</code>. To see the changes you&rsquo;ve
made, simply refresh your browser.</p>
<h2><a class='title-link' name='enabling-javascript-backend-development' href='#enabling-javascript-backend-development'></a> Enabling JavaScript backend development</h2>
<p>Polymer is only providing a UI toolkit for Home Assistant. All data management and interaction with
the server is done by <code>home-assistant-js</code> leveraging NuclearJS. To enable JavaScript development:</p>
<figure class='code'><figcaption><span></span></figcaption><div class="highlight"><table><tr><td class="gutter"><pre class="line-numbers"><span class='line-number'>1</span>
<span class='line-number'>2</span>
<span class='line-number'>3</span>
</pre></td><td class='code'><pre><code class='bash'><span class='line'><span class="nb">cd </span>homeassistant/components/frontend/www_static/home-assistant-polymer/
</span><span class='line'>npm run setup_js_dev
</span><span class='line'>npm run js_dev
</span></code></pre></td></tr></table></div></figure>
<p><code>npm run js_dev</code> will start the process that will ensure that your latest changes to the JavaScript
files will be loaded when you refresh the page. This command has to be always running while working
on home-assistant-js.</p>
<p>After your changes have been accepted into the <code>home-assistant-js</code> repository, we&rsquo;ll have to update
Home Assistant Polymer to use the latest version. This can be done by updating <code>package.json</code>. Look
for the line that contains <code>home-assistant-js</code> and update the SHA to the SHA of your commit.</p>
<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>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.
<ul>
<li>Compile all used JavaScript to <code>_app_compiled.js</code>.</li>
<li>Install Bower dependencies.</li>
<li>Vulcanize all Webcomponents to <code>frontend.vulcan.html</code>.</li>
<li>Minify <code>frontend.vulcan.html</code> and save it as <code>frontend.html</code>.</li>
</ul>
</li>
<li>Copy the webcomponents polyfill <code>webcomponents-lite.min.js</code> from <strong>home-assistant-polymer</strong> to <code>components/frontend/www_static/webcomponents-lite.min.js</code>.</li>
<li>Copy the final frontend build <code>frontend.html</code> from <strong>home-assistant-polymer</strong> to <code>components/frontend/www_static/frontend.html</code>.</li>
<li>Generate MD5 hash of <code>frontend.html</code> to signal caches to redownload the UI.</li>
</ul>
<p class='img'>
<img src='/images/frontend/polymer-build-architecture.png' alt='Polymer build architecture diagram' />
</p>
<h1><a class='title-link' name='adding-state-cards' href='#adding-state-cards'></a> Adding state cards</h1>
<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 a state badge, the name of the entity, when the state has last changed and the current state or a control to interact with it.</p>
<p><img src='/images/frontend/frontend-cards.png' /></p>
<p>Some domains will be filtered out of the main view and are available through separate menu options. Examples are <code>group</code>, <code>script</code>, <code>scene</code>.</p>
<p>The different card types can be found <a href="https://github.com/balloob/home-assistant-polymer/tree/master/src/state-summary">here</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>camera</code>:
<em>(All files in this example link to their source-code)</em></p>
<ol>
<li>Add <code>'camera'</code> to the array <code>DOMAINS_WITH_CARD</code> in the file <a href="https://github.com/balloob/home-assistant-polymer/blob/master/src/util/state-card-type.js#L3-L4"><code>/util/state-card-type.js</code></a>.</li>
<li>Create the files <code>state-card-camera.html</code> and <code>state-card-camera.js</code> in the folder <a href="https://github.com/balloob/home-assistant-polymer/tree/master/src/state-summary"><code>/state-summary/</code></a>.</li>
<li>Add <code>require('./state-card-camera')</code> to <a href="https://github.com/balloob/home-assistant-polymer/blob/master/src/state-summary/state-card-content.js"><code>state-card-content.js</code></a>.</li>
<li>Add <code>&lt;link rel="import" href="state-card-camera.html"&gt;</code> to <a href="https://github.com/balloob/home-assistant-polymer/blob/master/src/state-summary/state-card-content.html"><code>state-card-content.html</code></a>.</li>
</ol>
<h1><a class='title-link' name='more-info-screens-for-custom-types' href='#more-info-screens-for-custom-types'></a> More info screens for custom types</h1>
<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>camera</code>:<br/>
<em>(All files in this example link to their source-code)</em></p>
<ol>
<li>Add <code>'camera'</code> to the array <code>DOMAINS_WITH_MORE_INFO</code> in the file <a href="https://github.com/balloob/home-assistant-polymer/blob/master/src/util/state-more-info-type.js#L1"><code>util/state-more-info-type.js</code></a>.</li>
<li>Create the files <code>more-info-camera.html</code> and <code>more-info-camera.js</code> in the folder <a href="https://github.com/balloob/home-assistant-polymer/tree/master/src/more-infos"><code>/more-infos</code></a>.</li>
<li>Add <code>require('./more-info-camera')</code> to <a href="https://github.com/balloob/home-assistant-polymer/blob/master/src/more-infos/more-info-content.js"><code>more-info-content.js</code></a></li>
<li>Add <code>&lt;link rel="import" href="more-info-camera.html"&gt;</code> to <a href="https://github.com/balloob/home-assistant-polymer/blob/master/src/more-infos/more-info-content.html"><code>more-info-content.html</code></a></li>
</ol>
</article>
</div>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item">
<p class="copyright">
<span class="credit">Powered by <a href="http://octopress.org">Octopress</a>, <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>. Hosted by <a href='https://pages.github.com/'>GitHub</a> and served by <a href='https://cloudflare.com'>CloudFlare</a>.</span>
</p>
</div>
</div>
</div>
</footer>
<!--[if lt IE 7]>
<p class="chromeframe">You are using an <strong>outdated</strong> browser. Please <a href="http://browsehappy.com/">upgrade your browser</a> or <a href="http://www.google.com/chromeframe/?redirect=true">activate Google Chrome Frame</a> to improve your experience.</p>
<![endif]-->
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
g.src=('https:'==location.protocol?'//ssl':'//www')+'.google-analytics.com/ga.js';
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>
<script>document.location = '/developers/frontend/';</script>

251
developers/frontend/index.html Normal file
View file

@ -0,0 +1,251 @@
<!doctype html>
<!--[if lt IE 7]> <html class="no-js lt-ie9 lt-ie8 lt-ie7"> <![endif]-->
<!--[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="Paulus Schoutsen">
<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">
<meta property="og:url" content="https://home-assistant.io/developers/frontend/">
<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/home-assistant-logo-2164x2164.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='/images/favicon-192x192.png'> Home Assistant
</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>
<ul>
<li><a href='/getting-started/'>Installing Home Assistant</a></li>
<li><a href='/getting-started/configuration/'>Configuration basics</a></li>
<li><a href='/getting-started/devices/'>Adding devices</a></li>
<li><a href='/getting-started/presence-detection/'>Presence detection</a></li>
<li><a href='/getting-started/automation/'>Automation</a></li>
<li><a href='/cookbook'>Configuration cookbook</a></li>
</ul>
</li>
<li><a href='/components/'>Components</a></li>
<li>
<a href="/developers/">Developers</a>
<ul>
<li><a href="/developers/architecture/">Architecture</a></li>
<li><a href="/developers/frontend/">Frontend development</a></li>
<li><a href="/developers/creating_components/">
Creating components
</a></li>
<li><a href="/developers/add_new_platform/">
Adding platform support
</a></li>
<li><a href="/developers/api/">API</a></li>
<li><a href="/developers/credits/">Credits</a></li>
</ul>
</li>
<li><a href="/blog/">Blog</a></li>
<li><a href="/help/">Need help?</a></li>
</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 uses <a href="https://www.polymer-project.org/">Polymer</a> for the UI and <a href="http://optimizely.github.io/nuclear-js/">NuclearJS</a> for all data management.</p>
<ul>
<li>Polymer allows building encapsulated custom HTML elements.<br />
<a href="https://github.com/balloob/home-assistant-polymer">Home-Assistant-Polymer source code on GitHub.</a></li>
<li>NuclearJS is a reactive flux built with ImmutableJS data structures.<br />
<a href="https://github.com/balloob/home-assistant-js">Home-Assistant-JS source code on GitHub.</a></li>
</ul>
<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>
<h1><a class="title-link" name="turning-on-development-mode" href="#turning-on-development-mode"></a> Turning on development mode</h1>
<p>Home Assistant will by default serve the compiled version of the frontend. To change it so that each component and JavaScript are served separately, update your <code>configuration.yaml</code> to have these lines:</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre><span class="key">http</span>:
<span class="key">development</span>: <span class="string"><span class="content">1</span></span>
</pre></div>
</div>
</div>
<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 will have to do this by running from the command line:</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>$ git submodule update --init
</pre></div>
</div>
</div>
<p>After checking out the frontend code, you will have to install the frontend dependencies. Firing off a build of the frontend by running <code>script/build_frontend</code> will ensure they get installed.</p>
<p>Once this is done, you can start editting the webcomponents in the folder <code>homeassistant/components/frontend/www_static/home-assistant-polymer/src</code>. To see the changes you’ve made, simply refresh your browser.</p>
<h2><a class="title-link" name="enabling-javascript-backend-development" href="#enabling-javascript-backend-development"></a> Enabling JavaScript backend development</h2>
<p>Polymer is only providing a UI toolkit for Home Assistant. All data management and interaction with the server is done by <code>home-assistant-js</code> leveraging NuclearJS. To enable JavaScript development:</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>$ cd homeassistant/components/frontend/www_static/home-assistant-polymer/
$ npm run setup_js_dev
$ npm run js_dev
</pre></div>
</div>
</div>
<p><code>npm run js_dev</code> will start the process that will ensure that your latest changes to the JavaScript files will be loaded when you refresh the page. This command has to be always running while working on home-assistant-js.</p>
<p>After your changes have been accepted into the <code>home-assistant-js</code> repository, we’ll have to update Home Assistant Polymer to use the latest version. This can be done by updating <code>package.json</code>. Look for the line that contains <code>home-assistant-js</code> and update the SHA to the SHA of your commit.</p>
<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>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.
<ul>
<li>Compile all used JavaScript to <code>_app_compiled.js</code>.</li>
<li>Install Bower dependencies.</li>
<li>Vulcanize all Webcomponents to <code>frontend.vulcan.html</code>.</li>
<li>Minify <code>frontend.vulcan.html</code> and save it as <code>frontend.html</code>.</li>
</ul>
</li>
<li>Copy the webcomponents polyfill <code>webcomponents-lite.min.js</code> from <strong>home-assistant-polymer</strong> to <code>components/frontend/www_static/webcomponents-lite.min.js</code>.</li>
<li>Copy the final frontend build <code>frontend.html</code> from <strong>home-assistant-polymer</strong> to <code>components/frontend/www_static/frontend/</code>.</li>
<li>Generate MD5 hash of <code>frontend.html</code> to signal caches to redownload the UI.</li>
</ul>
<p class="img">
<img src="/images/frontend/polymer-build-architecture.png" alt="Polymer build architecture diagram" />
Polymer build architecture diagram
</p>
<h1><a class="title-link" name="adding-state-cards" href="#adding-state-cards"></a> Adding state cards</h1>
<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 a state badge, the name of the entity, when the state has last changed and the current state or a control to interact with it.</p>
<p><img src="/images/frontend/frontend-cards.png" alt="Cards in the frontend" /></p>
<p>The different card types can be found <a href="https://github.com/balloob/home-assistant-polymer/tree/master/src/state-summary">here</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>camera</code>: <em>(All files in this example link to their source-code)</em></p>
<ol>
<li>Add <code>'camera'</code> to the array <code>DOMAINS_WITH_CARD</code> in the file <a href="https://github.com/balloob/home-assistant-polymer/blob/master/src/util/state-card-type.js#L3-L4"><code>/util/state-card-type.js</code></a>.</li>
<li>Create the files <code>state-card-camera.html</code> and <code>state-card-camera.js</code> in the folder <a href="https://github.com/balloob/home-assistant-polymer/tree/master/src/state-summary"><code>/state-summary/</code></a>.</li>
<li>Add <code>require('./state-card-camera')</code> to <a href="https://github.com/balloob/home-assistant-polymer/blob/master/src/state-summary/state-card-content.js"><code>state-card-content.js</code></a>.</li>
<li>Add <code>&lt;link rel="import" href="state-card-camera.html"&gt;</code> to <a href="https://github.com/balloob/home-assistant-polymer/blob/master/src/state-summary/state-card-content.html"><code>state-card-content.html</code></a>.</li>
</ol>
<h1><a class="title-link" name="more-info-screens-for-custom-types" href="#more-info-screens-for-custom-types"></a> More info screens for custom types</h1>
<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>camera</code>:<br />
<em>(All files in this example link to their source-code)</em></p>
<ol>
<li>Add <code>'camera'</code> to the array <code>DOMAINS_WITH_MORE_INFO</code> in the file <a href="https://github.com/balloob/home-assistant-polymer/blob/master/src/util/state-more-info-type.js#L1"><code>util/state-more-info-type.js</code></a>.</li>
<li>Create the files <code>more-info-camera.html</code> and <code>more-info-camera.js</code> in the folder <a href="https://github.com/balloob/home-assistant-polymer/tree/master/src/more-infos"><code>/more-infos</code></a>.</li>
<li>Add <code>require('./more-info-camera')</code> to <a href="https://github.com/balloob/home-assistant-polymer/blob/master/src/more-infos/more-info-content.js"><code>more-info-content.js</code></a></li>
<li>Add <code>&lt;link rel="import" href="more-info-camera.html"&gt;</code> to <a href="https://github.com/balloob/home-assistant-polymer/blob/master/src/more-infos/more-info-content.html"><code>more-info-content.html</code></a></li>
</ol>
</article>
</div>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item">
<p class="copyright">
<span class="credit">Powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>. Hosted by <a href='https://pages.github.com/'>GitHub</a> and served by <a href='https://cloudflare.com'>CloudFlare</a>.</span>
</p>
</div>
</div>
</div>
</footer>
<!--[if lt IE 7]>
<p class="chromeframe">You are using an <strong>outdated</strong> browser. Please <a href="http://browsehappy.com/">upgrade your browser</a> or <a href="http://www.google.com/chromeframe/?redirect=true">activate Google Chrome Frame</a> to improve your experience.</p>
<![endif]-->
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
g.src=('https:'==location.protocol?'//ssl':'//www')+'.google-analytics.com/ga.js';
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>

99
developers/index.html
View file

@ -5,8 +5,6 @@
<!--[if gt IE 8]><!--> <html> <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
@ -32,7 +30,6 @@
<link rel='icon' type='image/png' href='/images/favicon-192x192.png' sizes='192x192' />
</head>
<body >
<header>
@ -54,10 +51,10 @@
<a href="/getting-started/">Getting started</a>
<ul>
<li><a href='/getting-started/'>Installing Home Assistant</a></li>
<li><a href='/getting-started/configuration.html'>Configuration basics</a></li>
<li><a href='/getting-started/devices.html'>Adding devices</a></li>
<li><a href='/getting-started/presence-detection.html'>Presence detection</a></li>
<li><a href='/getting-started/automation.html'>Automation</a></li>
<li><a href='/getting-started/configuration/'>Configuration basics</a></li>
<li><a href='/getting-started/devices/'>Adding devices</a></li>
<li><a href='/getting-started/presence-detection/'>Presence detection</a></li>
<li><a href='/getting-started/automation/'>Automation</a></li>
<li><a href='/cookbook'>Configuration cookbook</a></li>
</ul>
</li>
@ -65,26 +62,24 @@
<li>
<a href="/developers/">Developers</a>
<ul>
<li><a href="/developers/architecture.html">Architecture</a></li>
<li><a href="/developers/frontend.html">Frontend development</a></li>
<li><a href="/developers/creating_components.html">
<li><a href="/developers/architecture/">Architecture</a></li>
<li><a href="/developers/frontend/">Frontend development</a></li>
<li><a href="/developers/creating_components/">
Creating components
</a></li>
<li><a href="/developers/add_new_platform.html">
<li><a href="/developers/add_new_platform/">
Adding platform support
</a></li>
<li><a href="/developers/api.html">API</a></li>
<li><a href="/developers/credits.html">Credits</a></li>
<li><a href="/developers/api/">API</a></li>
<li><a href="/developers/credits/">Credits</a></li>
</ul>
</li>
<li><a href="/blog/">Blog</a></li>
<li><a href="/help/">Need help?</a></li>
</ul>
</nav>
</div>
</div>
</div>
</header>
@ -113,59 +108,56 @@
<p>Home Assistant is open-source and MIT licensed. The source can be found here:</p>
<ul>
<li><a href="https://github.com/balloob/home-assistant">home-assistant</a> - Python server-backend</li>
<li><a href="https://github.com/balloob/home-assistant-js">home-assistant-js</a> - javascript-backend powering the client</li>
<li><a href="https://github.com/balloob/home-assistant-polymer">home-assistant-polymer</a> - Polymer UI</li>
<li><a href="https://github.com/balloob/home-assistant">home-assistant</a> - Python server-backend</li>
<li><a href="https://github.com/balloob/home-assistant-js">home-assistant-js</a> - javascript-backend powering the client</li>
<li><a href="https://github.com/balloob/home-assistant-polymer">home-assistant-polymer</a> - Polymer UI</li>
</ul>
<h3><a class='title-link' name='starting-development' href='#starting-development'></a> Starting development</h3>
<h3><a class="title-link" name="starting-development" href="#starting-development"></a> Starting development</h3>
<p>You will need to setup a development environment if you want to start developing a new feature or component for Home Assistant perform theses steps</p>
<figure class='code'><figcaption><span></span></figcaption><div class="highlight"><table><tr><td class="gutter"><pre class="line-numbers"><span class='line-number'>1</span>
<span class='line-number'>2</span>
<span class='line-number'>3</span>
</pre></td><td class='code'><pre><code class='bash'><span class='line'>git clone https://github.com/balloob/home-assistant.git
</span><span class='line'><span class="nb">cd </span>home-assistant
</span><span class='line'>script/setup
</span></code></pre></td></tr></table></div></figure>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>$ git clone https://github.com/balloob/home-assistant.git
$ cd home-assistant
$ script/setup
</pre></div>
</div>
</div>
<p>After following these steps, running <code>hass</code> will invoke your local installation.</p>
<h3><a class='title-link' name='submitting-improvements' href='#submitting-improvements'></a> Submitting improvements</h3>
<h3><a class="title-link" name="submitting-improvements" href="#submitting-improvements"></a> Submitting improvements</h3>
<p>Improvements to Home Assistant should be submitted one feature at a time using Github pull
<p>Improvements to Home Assistant should be submitted one feature at a time using Github pull<br />
requests.</p>
<ol>
<li>Go to <a href="https://github.com/balloob/home-assistant">the Home Assistant repository</a> and click fork in the top right.</li>
<li>Follow steps in the previous section but with your forked repository.</li>
<li>Create a new branch to hold your changes<br>
<li>Go to <a href="https://github.com/balloob/home-assistant">the Home Assistant repository</a> and click fork in the top right.</li>
<li>Follow steps in the previous section but with your forked repository.</li>
<li>Create a new branch to hold your changes<br />
<code>git checkout -b some-feature</code></li>
<li>Make the changes you want</li>
<li>Check your changes for style violations<br>
<li>Make the changes you want</li>
<li>Check your changes for style violations<br />
<code>./script/lint</code></li>
<li>Commit the changes<br>
<code>git add .</code><br>
<li>Commit the changes<br />
<code>git add .</code><br />
<code>git commit -m "Added some-feature"</code></li>
<li>Push your commited changes back to your fork on Github<br>
<li>Push your commited changes back to your fork on Github<br />
<code>git push origin HEAD</code></li>
<li>Follow <a href="https://help.github.com/articles/creating-a-pull-request/">these steps</a> to create your
<li>Follow <a href="https://help.github.com/articles/creating-a-pull-request/">these steps</a> to create your<br />
pull request.</li>
</ol>
<h3><a class='title-link' name='further-reading' href='#further-reading'></a> Further reading</h3>
<h3><a class="title-link" name="further-reading" href="#further-reading"></a> Further reading</h3>
<ul>
<li><a href="/developers/architecture.html">Home Assistant Architecture</a></li>
<li><a href="/developers/frontend.html">Frontend development</a></li>
<li><a href="/developers/creating_components.html">Creating a custom component</a></li>
<li><a href="/developers/add_new_platform.html">Adding support for a new platform</a></li>
<li><a href="/developers/api.html">Rest API</a></li>
<li><a href="/developers/website.html">Website</a></li>
<li><a href="/developers/architecture/">Home Assistant Architecture</a></li>
<li><a href="/developers/frontend/">Frontend development</a></li>
<li><a href="/developers/creating_components/">Creating a custom component</a></li>
<li><a href="/developers/add_new_platform/">Adding support for a new platform</a></li>
<li><a href="/developers/api/">Rest API</a></li>
<li><a href="/developers/website/">Website</a></li>
</ul>
@ -184,32 +176,23 @@ pull request.</li>
<div class="grid">
<div class="grid__item">
<p class="copyright">
<span class="credit">Powered by <a href="http://octopress.org">Octopress</a>, <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>. Hosted by <a href='https://pages.github.com/'>GitHub</a> and served by <a href='https://cloudflare.com'>CloudFlare</a>.</span>
<span class="credit">Powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>. Hosted by <a href='https://pages.github.com/'>GitHub</a> and served by <a href='https://cloudflare.com'>CloudFlare</a>.</span>
</p>
</div>
</div>
</div>
</footer>
<!--[if lt IE 7]>
<p class="chromeframe">You are using an <strong>outdated</strong> browser. Please <a href="http://browsehappy.com/">upgrade your browser</a> or <a href="http://www.google.com/chromeframe/?redirect=true">activate Google Chrome Frame</a> to improve your experience.</p>
<![endif]-->
<script>
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
g.src=('https:'==location.protocol?'//ssl':'//www')+'.google-analytics.com/ga.js';
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>

371
developers/python_api.html
View file

@ -1,370 +1 @@
<!doctype html>
<!--[if lt IE 7]> <html class="no-js lt-ie9 lt-ie8 lt-ie7"> <![endif]-->
<!--[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 API - Home Assistant</title>
<meta name="author" content="Paulus Schoutsen">
<meta name="description" content="Home Assistant Python API documentation">
<meta name="viewport" content="width=device-width">
<link rel="canonical" href="https://home-assistant.io/developers/python_api.html">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="Python API">
<meta property="og:site_name" content="Home Assistant">
<meta property="og:url" content="https://home-assistant.io/developers/python_api.html">
<meta property="og:type" content="website">
<meta property="og:description" content="Home Assistant Python API documentation">
<meta property="og:image" content="https://home-assistant.io/images/home-assistant-logo-2164x2164.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='/images/favicon-192x192.png'> Home Assistant
</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>
<ul>
<li><a href='/getting-started/'>Installing Home Assistant</a></li>
<li><a href='/getting-started/configuration.html'>Configuration basics</a></li>
<li><a href='/getting-started/devices.html'>Adding devices</a></li>
<li><a href='/getting-started/presence-detection.html'>Presence detection</a></li>
<li><a href='/getting-started/automation.html'>Automation</a></li>
<li><a href='/cookbook'>Configuration cookbook</a></li>
</ul>
</li>
<li><a href='/components/'>Components</a></li>
<li>
<a href="/developers/">Developers</a>
<ul>
<li><a href="/developers/architecture.html">Architecture</a></li>
<li><a href="/developers/frontend.html">Frontend development</a></li>
<li><a href="/developers/creating_components.html">
Creating components
</a></li>
<li><a href="/developers/add_new_platform.html">
Adding platform support
</a></li>
<li><a href="/developers/api.html">API</a></li>
<li><a href="/developers/credits.html">Credits</a></li>
</ul>
</li>
<li><a href="/blog/">Blog</a></li>
<li><a href="/help/">Need help?</a></li>
</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 API
</h1>
</header>
<hr class="divider">
<p>In the package <a href="https://github.com/balloob/home-assistant/blob/master/homeassistant/remote.py"><code>homeassistant.remote</code></a> a Python API on top of the <a href="/developers/api.html">HTTP API</a> can be found.</p>
<p>This page is not a full documentation it&rsquo;s more a collection of some example. A simple way to get all current entities is to visit the &ldquo;Set State&rdquo; page in the &ldquo;Developer Tools&rdquo;. For the examples below just choose one from the available entries. Here the sensor <code>sensor.office_temperature</code> and the switch <code>switch.livingroom_pin_2</code> are used.</p>
<p>First import the module and setup the basics.</p>
<figure class='code'><figcaption><span></span></figcaption><div class="highlight"><table><tr><td class="gutter"><pre class="line-numbers"><span class='line-number'>1</span>
<span class='line-number'>2</span>
<span class='line-number'>3</span>
<span class='line-number'>4</span>
</pre></td><td class='code'><pre><code class='python'><span class='line'><span class="kn">import</span> <span class="nn">homeassistant.remote</span> <span class="kn">as</span> <span class="nn">remote</span>
</span><span class='line'>
</span><span class='line'><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">&#39;host&#39;</span><span class="p">,</span> <span class="s">&#39;password&#39;</span><span class="p">)</span>
</span><span class='line'><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>
</span></code></pre></td></tr></table></div></figure>
<p>This snippets shows how to use the <code>homeassistant.remote</code> package in another way.</p>
<figure class='code'><figcaption><span></span></figcaption><div class="highlight"><table><tr><td class="gutter"><pre class="line-numbers"><span class='line-number'>1</span>
<span class='line-number'>2</span>
<span class='line-number'>3</span>
<span class='line-number'>4</span>
<span class='line-number'>5</span>
<span class='line-number'>6</span>
</pre></td><td class='code'><pre><code class='python'><span class='line'><span class="kn">import</span> <span class="nn">homeassistant.remote</span> <span class="kn">as</span> <span class="nn">remote</span>
</span><span class='line'>
</span><span class='line'><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">&#39;host&#39;</span><span class="p">,</span> <span class="s">&#39;password&#39;</span><span class="p">)</span>
</span><span class='line'><span class="n">hass</span> <span class="o">=</span> <span class="n">remote</span><span class="o">.</span><span class="n">HomeAssistant</span><span class="p">(</span><span class="n">api</span><span class="p">)</span>
</span><span class='line'><span class="n">hass</span><span class="o">.</span><span class="n">start</span><span class="p">()</span>
</span><span class='line'><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">&#39;group.living_room&#39;</span><span class="p">)</span>
</span></code></pre></td></tr></table></div></figure>
<h3><a class='title-link' name='get-details-about-servies-and-events' href='#get-details-about-servies-and-events'></a> Get details about servies and events</h3>
<p>Similar to the output in the &ldquo;Developer Tools&rdquo; of the frontend.</p>
<figure class='code'><figcaption><span></span></figcaption><div class="highlight"><table><tr><td class="gutter"><pre class="line-numbers"><span class='line-number'>1</span>
<span class='line-number'>2</span>
<span class='line-number'>3</span>
<span class='line-number'>4</span>
<span class='line-number'>5</span>
<span class='line-number'>6</span>
<span class='line-number'>7</span>
<span class='line-number'>8</span>
<span class='line-number'>9</span>
<span class='line-number'>10</span>
<span class='line-number'>11</span>
<span class='line-number'>12</span>
<span class='line-number'>13</span>
</pre></td><td class='code'><pre><code class='python'><span class='line'><span class="kn">import</span> <span class="nn">homeassistant.remote</span> <span class="kn">as</span> <span class="nn">remote</span>
</span><span class='line'>
</span><span class='line'><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">&#39;host&#39;</span><span class="p">,</span> <span class="s">&#39;password&#39;</span><span class="p">)</span>
</span><span class='line'>
</span><span class='line'><span class="k">print</span><span class="p">(</span><span class="s">&#39;-- Available services:&#39;</span><span class="p">)</span>
</span><span class='line'><span class="n">services</span> <span class="o">=</span> <span class="n">remote</span><span class="o">.</span><span class="n">get_services</span><span class="p">(</span><span class="n">api</span><span class="p">)</span>
</span><span class='line'><span class="k">for</span> <span class="n">service</span> <span class="ow">in</span> <span class="n">services</span><span class="p">:</span>
</span><span class='line'> <span class="k">print</span><span class="p">(</span><span class="n">service</span><span class="p">[</span><span class="s">&#39;services&#39;</span><span class="p">])</span>
</span><span class='line'>
</span><span class='line'><span class="k">print</span><span class="p">(</span><span class="s">&#39;</span><span class="se">\n</span><span class="s">-- Available event&#39;</span><span class="p">)</span>
</span><span class='line'><span class="n">events</span> <span class="o">=</span> <span class="n">remote</span><span class="o">.</span><span class="n">get_event_listeners</span><span class="p">(</span><span class="n">api</span><span class="p">)</span>
</span><span class='line'><span class="k">for</span> <span class="n">event</span> <span class="ow">in</span> <span class="n">events</span><span class="p">:</span>
</span><span class='line'> <span class="k">print</span><span class="p">(</span><span class="n">event</span><span class="p">)</span>
</span></code></pre></td></tr></table></div></figure>
<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 the <code>get_state</code> method is used.</p>
<figure class='code'><figcaption><span></span></figcaption><div class="highlight"><table><tr><td class="gutter"><pre class="line-numbers"><span class='line-number'>1</span>
<span class='line-number'>2</span>
<span class='line-number'>3</span>
<span class='line-number'>4</span>
<span class='line-number'>5</span>
<span class='line-number'>6</span>
<span class='line-number'>7</span>
<span class='line-number'>8</span>
<span class='line-number'>9</span>
</pre></td><td class='code'><pre><code class='python'><span class='line'><span class="kn">import</span> <span class="nn">homeassistant.remote</span> <span class="kn">as</span> <span class="nn">remote</span>
</span><span class='line'>
</span><span class='line'><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">&#39;host&#39;</span><span class="p">,</span> <span class="s">&#39;password&#39;</span><span class="p">)</span>
</span><span class='line'><span class="n">office_temperature</span> <span class="o">=</span> <span class="n">remote</span><span class="o">.</span><span class="n">get_state</span><span class="p">(</span><span class="n">api</span><span class="p">,</span> <span class="s">&#39;sensor.office_temperature&#39;</span><span class="p">)</span>
</span><span class='line'><span class="k">print</span><span class="p">(</span><span class="s">&#39;{} is {} {}.&#39;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">office_temperature</span><span class="o">.</span><span class="n">attributes</span><span class="p">[</span><span class="s">&#39;friendly_name&#39;</span><span class="p">],</span>
</span><span class='line'> <span class="n">office_temperature</span><span class="o">.</span><span class="n">state</span><span class="p">,</span>
</span><span class='line'> <span class="n">office_temperature</span><span class="o">.</span><span class="n">attributes</span><span class="p">[</span><span class="s">&#39;unit_of_measurement&#39;</span><span class="p">]</span>
</span><span class='line'> <span class="p">)</span>
</span><span class='line'> <span class="p">)</span>
</span></code></pre></td></tr></table></div></figure>
<p>The output is composed out of the details which are stored for this entity.</p>
<figure class='code'><figcaption><span></span></figcaption><div class="highlight"><table><tr><td class="gutter"><pre class="line-numbers"><span class='line-number'>1</span>
</pre></td><td class='code'><pre><code class='bash'><span class='line'>Office Temperature is <span class="m">19</span> °C.
</span></code></pre></td></tr></table></div></figure>
<p>The exact same thing is working for a switch. The difference is that both entities have different attributes.</p>
<figure class='code'><figcaption><span></span></figcaption><div class="highlight"><table><tr><td class="gutter"><pre class="line-numbers"><span class='line-number'>1</span>
<span class='line-number'>2</span>
<span class='line-number'>3</span>
<span class='line-number'>4</span>
<span class='line-number'>5</span>
<span class='line-number'>6</span>
<span class='line-number'>7</span>
<span class='line-number'>8</span>
</pre></td><td class='code'><pre><code class='python'><span class='line'><span class="kn">import</span> <span class="nn">homeassistant.remote</span> <span class="kn">as</span> <span class="nn">remote</span>
</span><span class='line'>
</span><span class='line'><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">&#39;host&#39;</span><span class="p">,</span> <span class="s">&#39;password&#39;</span><span class="p">)</span>
</span><span class='line'><span class="n">switch_livingroom</span> <span class="o">=</span> <span class="n">remote</span><span class="o">.</span><span class="n">get_state</span><span class="p">(</span><span class="n">api</span><span class="p">,</span> <span class="s">&#39;switch.livingroom_pin_2&#39;</span><span class="p">)</span>
</span><span class='line'><span class="k">print</span><span class="p">(</span><span class="s">&#39;{} is {}.&#39;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">switch_livingroom</span><span class="o">.</span><span class="n">attributes</span><span class="p">[</span><span class="s">&#39;friendly_name&#39;</span><span class="p">],</span>
</span><span class='line'> <span class="n">switch_livingroom</span><span class="o">.</span><span class="n">state</span>
</span><span class='line'> <span class="p">)</span>
</span><span class='line'> <span class="p">)</span>
</span></code></pre></td></tr></table></div></figure>
<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&rsquo;s possible to set the state.</p>
<figure class='code'><figcaption><span></span></figcaption><div class="highlight"><table><tr><td class="gutter"><pre class="line-numbers"><span class='line-number'>1</span>
<span class='line-number'>2</span>
<span class='line-number'>3</span>
<span class='line-number'>4</span>
<span class='line-number'>5</span>
<span class='line-number'>6</span>
</pre></td><td class='code'><pre><code class='python'><span class='line'><span class="kn">import</span> <span class="nn">homeassistant.remote</span> <span class="kn">as</span> <span class="nn">remote</span>
</span><span class='line'><span class="kn">from</span> <span class="nn">homeassistant.const</span> <span class="kn">import</span> <span class="n">STATE_ON</span>
</span><span class='line'>
</span><span class='line'><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">&#39;host&#39;</span><span class="p">,</span> <span class="s">&#39;password&#39;</span><span class="p">)</span>
</span><span class='line'><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">&#39;sensor.office_temperature&#39;</span><span class="p">,</span> <span class="n">new_state</span><span class="o">=</span><span class="mi">123</span><span class="p">)</span>
</span><span class='line'><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">&#39;switch.livingroom_pin_2&#39;</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>
</span></code></pre></td></tr></table></div></figure>
<p>The state will be set to those value until the next update occurs.</p>
<h3><a class='title-link' name='blinking-all-entites-of-a-domain' href='#blinking-all-entites-of-a-domain'></a> Blinking all entites of a domain</h3>
<p>If you want to turn on all entities of a domain, just a service which was retrieved by <code>get_services</code>.</p>
<figure class='code'><figcaption><span></span></figcaption><div class="highlight"><table><tr><td class="gutter"><pre class="line-numbers"><span class='line-number'>1</span>
<span class='line-number'>2</span>
<span class='line-number'>3</span>
<span class='line-number'>4</span>
<span class='line-number'>5</span>
<span class='line-number'>6</span>
<span class='line-number'>7</span>
<span class='line-number'>8</span>
<span class='line-number'>9</span>
</pre></td><td class='code'><pre><code class='python'><span class='line'><span class="kn">import</span> <span class="nn">time</span>
</span><span class='line'><span class="kn">import</span> <span class="nn">homeassistant.remote</span> <span class="kn">as</span> <span class="nn">remote</span>
</span><span class='line'>
</span><span class='line'><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">&#39;host&#39;</span><span class="p">,</span> <span class="s">&#39;password&#39;</span><span class="p">)</span>
</span><span class='line'><span class="n">domain</span> <span class="o">=</span> <span class="s">&#39;switch&#39;</span>
</span><span class='line'>
</span><span class='line'><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">&#39;turn_on&#39;</span><span class="p">)</span>
</span><span class='line'><span class="n">time</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="mi">10</span><span class="p">)</span>
</span><span class='line'><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">&#39;turn_off&#39;</span><span class="p">)</span>
</span></code></pre></td></tr></table></div></figure>
<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. The ID of the entity is needed as attribute.</p>
<figure class='code'><figcaption><span></span></figcaption><div class="highlight"><table><tr><td class="gutter"><pre class="line-numbers"><span class='line-number'>1</span>
<span class='line-number'>2</span>
<span class='line-number'>3</span>
<span class='line-number'>4</span>
<span class='line-number'>5</span>
<span class='line-number'>6</span>
<span class='line-number'>7</span>
<span class='line-number'>8</span>
<span class='line-number'>9</span>
<span class='line-number'>10</span>
</pre></td><td class='code'><pre><code class='python'><span class='line'><span class="kn">import</span> <span class="nn">time</span>
</span><span class='line'><span class="kn">import</span> <span class="nn">homeassistant.remote</span> <span class="kn">as</span> <span class="nn">remote</span>
</span><span class='line'>
</span><span class='line'><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">&#39;host&#39;</span><span class="p">,</span> <span class="s">&#39;password&#39;</span><span class="p">)</span>
</span><span class='line'><span class="n">domain</span> <span class="o">=</span> <span class="s">&#39;switch&#39;</span>
</span><span class='line'><span class="n">switch_name</span> <span class="o">=</span> <span class="s">&#39;switch.livingroom_pin_2&#39;</span>
</span><span class='line'>
</span><span class='line'><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">&#39;turn_on&#39;</span><span class="p">,</span> <span class="p">{</span><span class="s">&#39;entity_id&#39;</span><span class="p">:</span> <span class="s">&#39;{}&#39;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">switch_name</span><span class="p">)})</span>
</span><span class='line'><span class="n">time</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="mi">5</span><span class="p">)</span>
</span><span class='line'><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">&#39;turn_off&#39;</span><span class="p">,</span> <span class="p">{</span><span class="s">&#39;entity_id&#39;</span><span class="p">:</span> <span class="s">&#39;{}&#39;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">switch_name</span><span class="p">)})</span>
</span></code></pre></td></tr></table></div></figure>
<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>configuration.yaml</code> file.</p>
<figure class='code'><figcaption><span></span></figcaption><div class="highlight"><table><tr><td class="gutter"><pre class="line-numbers"><span class='line-number'>1</span>
<span class='line-number'>2</span>
<span class='line-number'>3</span>
<span class='line-number'>4</span>
<span class='line-number'>5</span>
<span class='line-number'>6</span>
<span class='line-number'>7</span>
</pre></td><td class='code'><pre><code class='python'><span class='line'><span class="kn">import</span> <span class="nn">homeassistant.remote</span> <span class="kn">as</span> <span class="nn">remote</span>
</span><span class='line'>
</span><span class='line'><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">&#39;host&#39;</span><span class="p">,</span> <span class="s">&#39;password&#39;</span><span class="p">)</span>
</span><span class='line'><span class="n">domain</span> <span class="o">=</span> <span class="s">&#39;notify&#39;</span>
</span><span class='line'><span class="n">data</span> <span class="o">=</span> <span class="p">{</span><span class="s">&quot;title&quot;</span><span class="p">:</span><span class="s">&quot;Test&quot;</span><span class="p">,</span> <span class="s">&quot;message&quot;</span><span class="p">:</span><span class="s">&quot;A simple test message from HA.&quot;</span><span class="p">}</span>
</span><span class='line'>
</span><span class='line'><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">&#39;jabber&#39;</span><span class="p">,</span> <span class="n">data</span><span class="p">)</span>
</span></code></pre></td></tr></table></div></figure>
<p>For more details please check the source of <a href="https://github.com/balloob/home-assistant/blob/master/homeassistant/remote.py">homeassistant.remote</a>.</p>
</article>
</div>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item">
<p class="copyright">
<span class="credit">Powered by <a href="http://octopress.org">Octopress</a>, <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>. Hosted by <a href='https://pages.github.com/'>GitHub</a> and served by <a href='https://cloudflare.com'>CloudFlare</a>.</span>
</p>
</div>
</div>
</div>
</footer>
<!--[if lt IE 7]>
<p class="chromeframe">You are using an <strong>outdated</strong> browser. Please <a href="http://browsehappy.com/">upgrade your browser</a> or <a href="http://www.google.com/chromeframe/?redirect=true">activate Google Chrome Frame</a> to improve your experience.</p>
<![endif]-->
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
g.src=('https:'==location.protocol?'//ssl':'//www')+'.google-analytics.com/ga.js';
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>
<script>document.location = '/developers/python_api/';</script>

303
developers/python_api/index.html Normal file
View file

@ -0,0 +1,303 @@
<!doctype html>
<!--[if lt IE 7]> <html class="no-js lt-ie9 lt-ie8 lt-ie7"> <![endif]-->
<!--[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 API - Home Assistant</title>
<meta name="author" content="Paulus Schoutsen">
<meta name="description" content="Home Assistant Python 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 API">
<meta property="og:site_name" content="Home Assistant">
<meta property="og:url" content="https://home-assistant.io/developers/python_api/">
<meta property="og:type" content="website">
<meta property="og:description" content="Home Assistant Python API documentation">
<meta property="og:image" content="https://home-assistant.io/images/home-assistant-logo-2164x2164.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='/images/favicon-192x192.png'> Home Assistant
</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>
<ul>
<li><a href='/getting-started/'>Installing Home Assistant</a></li>
<li><a href='/getting-started/configuration/'>Configuration basics</a></li>
<li><a href='/getting-started/devices/'>Adding devices</a></li>
<li><a href='/getting-started/presence-detection/'>Presence detection</a></li>
<li><a href='/getting-started/automation/'>Automation</a></li>
<li><a href='/cookbook'>Configuration cookbook</a></li>
</ul>
</li>
<li><a href='/components/'>Components</a></li>
<li>
<a href="/developers/">Developers</a>
<ul>
<li><a href="/developers/architecture/">Architecture</a></li>
<li><a href="/developers/frontend/">Frontend development</a></li>
<li><a href="/developers/creating_components/">
Creating components
</a></li>
<li><a href="/developers/add_new_platform/">
Adding platform support
</a></li>
<li><a href="/developers/api/">API</a></li>
<li><a href="/developers/credits/">Credits</a></li>
</ul>
</li>
<li><a href="/blog/">Blog</a></li>
<li><a href="/help/">Need help?</a></li>
</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 API
</h1>
</header>
<hr class="divider">
<p>In the package <a href="https://github.com/balloob/home-assistant/blob/master/homeassistant/remote.py"><code>homeassistant.remote</code></a> a Python API on top of the <a href="/developers/api/">HTTP API</a> can be found.</p>
<p>This page is not a full documentation it’s more a collection of some example. A simple way to get all current entities is to visit the “Set State” page in the “Developer Tools”. For the examples below just choose one from the available entries. Here the sensor <code>sensor.office_temperature</code> and the switch <code>switch.livingroom_pin_2</code> are used.</p>
<p>First import the module and setup the basics.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre><span class="keyword">import</span> <span class="include">homeassistant.remote</span> <span class="keyword">as</span> remote
api = remote.API(<span class="string"><span class="delimiter">'</span><span class="content">host</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">password</span><span class="delimiter">'</span></span>)
print(remote.validate_api(api))
</pre></div>
</div>
</div>
<p>This snippets shows how to use the <code>homeassistant.remote</code> package in another way.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre><span class="keyword">import</span> <span class="include">homeassistant.remote</span> <span class="keyword">as</span> remote
api = remote.API(<span class="string"><span class="delimiter">'</span><span class="content">host</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">password</span><span class="delimiter">'</span></span>)
hass = remote.HomeAssistant(api)
hass.start()
living_room = hass.states.get(<span class="string"><span class="delimiter">'</span><span class="content">group.living_room</span><span class="delimiter">'</span></span>)
</pre></div>
</div>
</div>
<h3><a class="title-link" name="get-details-about-servies-and-events" href="#get-details-about-servies-and-events"></a> Get details about servies and events</h3>
<p>Similar to the output in the “Developer Tools” of the frontend.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre><span class="keyword">import</span> <span class="include">homeassistant.remote</span> <span class="keyword">as</span> remote
api = remote.API(<span class="string"><span class="delimiter">'</span><span class="content">host</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">password</span><span class="delimiter">'</span></span>)
print(<span class="string"><span class="delimiter">'</span><span class="content">-- Available services:</span><span class="delimiter">'</span></span>)
services = remote.get_services(api)
<span class="keyword">for</span> service <span class="keyword">in</span> services:
print(service[<span class="string"><span class="delimiter">'</span><span class="content">services</span><span class="delimiter">'</span></span>])
print(<span class="string"><span class="delimiter">'</span><span class="char">\n</span><span class="content">-- Available event</span><span class="delimiter">'</span></span>)
events = remote.get_event_listeners(api)
<span class="keyword">for</span> event <span class="keyword">in</span> events:
print(event)
</pre></div>
</div>
</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 the <code>get_state</code> method is used.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre><span class="keyword">import</span> <span class="include">homeassistant.remote</span> <span class="keyword">as</span> remote
api = remote.API(<span class="string"><span class="delimiter">'</span><span class="content">host</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">password</span><span class="delimiter">'</span></span>)
office_temperature = remote.get_state(api, <span class="string"><span class="delimiter">'</span><span class="content">sensor.office_temperature</span><span class="delimiter">'</span></span>)
print(<span class="string"><span class="delimiter">'</span><span class="content">{} is {} {}.</span><span class="delimiter">'</span></span>.format(office_temperature.attributes[<span class="string"><span class="delimiter">'</span><span class="content">friendly_name</span><span class="delimiter">'</span></span>],
office_temperature.state,
office_temperature.attributes[<span class="string"><span class="delimiter">'</span><span class="content">unit_of_measurement</span><span class="delimiter">'</span></span>]
)
)
</pre></div>
</div>
</div>
<p>The output is composed out of the details which are stored for this entity.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>Office Temperature is 19 °C.
</pre></div>
</div>
</div>
<p>The exact same thing is working for a switch. The difference is that both entities have different attributes.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre><span class="keyword">import</span> <span class="include">homeassistant.remote</span> <span class="keyword">as</span> remote
api = remote.API(<span class="string"><span class="delimiter">'</span><span class="content">host</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">password</span><span class="delimiter">'</span></span>)
switch_livingroom = remote.get_state(api, <span class="string"><span class="delimiter">'</span><span class="content">switch.livingroom_pin_2</span><span class="delimiter">'</span></span>)
print(<span class="string"><span class="delimiter">'</span><span class="content">{} is {}.</span><span class="delimiter">'</span></span>.format(switch_livingroom.attributes[<span class="string"><span class="delimiter">'</span><span class="content">friendly_name</span><span class="delimiter">'</span></span>],
switch_livingroom.state
)
)
</pre></div>
</div>
</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.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre><span class="keyword">import</span> <span class="include">homeassistant.remote</span> <span class="keyword">as</span> remote
<span class="keyword">from</span> <span class="include">homeassistant.const</span> <span class="keyword">import</span> <span class="include">STATE_ON</span>
api = remote.API(<span class="string"><span class="delimiter">'</span><span class="content">host</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">password</span><span class="delimiter">'</span></span>)
remote.set_state(api, <span class="string"><span class="delimiter">'</span><span class="content">sensor.office_temperature</span><span class="delimiter">'</span></span>, new_state=<span class="integer">123</span>)
remote.set_state(api, <span class="string"><span class="delimiter">'</span><span class="content">switch.livingroom_pin_2</span><span class="delimiter">'</span></span>, new_state=STATE_ON)
</pre></div>
</div>
</div>
<p>The state will be set to those value until the next update occurs.</p>
<h3><a class="title-link" name="blinking-all-entites-of-a-domain" href="#blinking-all-entites-of-a-domain"></a> Blinking all entites of a domain</h3>
<p>If you want to turn on all entities of a domain, just a service which was retrieved by <code>get_services</code>.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre><span class="keyword">import</span> <span class="include">time</span>
<span class="keyword">import</span> <span class="include">homeassistant.remote</span> <span class="keyword">as</span> remote
api = remote.API(<span class="string"><span class="delimiter">'</span><span class="content">host</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">password</span><span class="delimiter">'</span></span>)
domain = <span class="string"><span class="delimiter">'</span><span class="content">switch</span><span class="delimiter">'</span></span>
remote.call_service(api, domain, <span class="string"><span class="delimiter">'</span><span class="content">turn_on</span><span class="delimiter">'</span></span>)
time.sleep(<span class="integer">10</span>)
remote.call_service(api, domain, <span class="string"><span class="delimiter">'</span><span class="content">turn_off</span><span class="delimiter">'</span></span>)
</pre></div>
</div>
</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. The ID of the entity is needed as attribute.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre><span class="keyword">import</span> <span class="include">time</span>
<span class="keyword">import</span> <span class="include">homeassistant.remote</span> <span class="keyword">as</span> remote
api = remote.API(<span class="string"><span class="delimiter">'</span><span class="content">host</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">password</span><span class="delimiter">'</span></span>)
domain = <span class="string"><span class="delimiter">'</span><span class="content">switch</span><span class="delimiter">'</span></span>
switch_name = <span class="string"><span class="delimiter">'</span><span class="content">switch.livingroom_pin_2</span><span class="delimiter">'</span></span>
remote.call_service(api, domain, <span class="string"><span class="delimiter">'</span><span class="content">turn_on</span><span class="delimiter">'</span></span>, {<span class="string"><span class="delimiter">'</span><span class="content">entity_id</span><span class="delimiter">'</span></span>: <span class="string"><span class="delimiter">'</span><span class="content">{}</span><span class="delimiter">'</span></span>.format(switch_name)})
time.sleep(<span class="integer">5</span>)
remote.call_service(api, domain, <span class="string"><span class="delimiter">'</span><span class="content">turn_off</span><span class="delimiter">'</span></span>, {<span class="string"><span class="delimiter">'</span><span class="content">entity_id</span><span class="delimiter">'</span></span>: <span class="string"><span class="delimiter">'</span><span class="content">{}</span><span class="delimiter">'</span></span>.format(switch_name)})
</pre></div>
</div>
</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>configuration.yaml</code> file.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre><span class="keyword">import</span> <span class="include">homeassistant.remote</span> <span class="keyword">as</span> remote
api = remote.API(<span class="string"><span class="delimiter">'</span><span class="content">host</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">password</span><span class="delimiter">'</span></span>)
domain = <span class="string"><span class="delimiter">'</span><span class="content">notify</span><span class="delimiter">'</span></span>
data = {<span class="string"><span class="delimiter">&quot;</span><span class="content">title</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">Test</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">message</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">A simple test message from HA.</span><span class="delimiter">&quot;</span></span>}
remote.call_service(api, domain, <span class="string"><span class="delimiter">'</span><span class="content">jabber</span><span class="delimiter">'</span></span>, data)
</pre></div>
</div>
</div>
<p>For more details please check the source of <a href="https://github.com/balloob/home-assistant/blob/master/homeassistant/remote.py">homeassistant.remote</a>.</p>
</article>
</div>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item">
<p class="copyright">
<span class="credit">Powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>. Hosted by <a href='https://pages.github.com/'>GitHub</a> and served by <a href='https://cloudflare.com'>CloudFlare</a>.</span>
</p>
</div>
</div>
</div>
</footer>
<!--[if lt IE 7]>
<p class="chromeframe">You are using an <strong>outdated</strong> browser. Please <a href="http://browsehappy.com/">upgrade your browser</a> or <a href="http://www.google.com/chromeframe/?redirect=true">activate Google Chrome Frame</a> to improve your experience.</p>
<![endif]-->
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
g.src=('https:'==location.protocol?'//ssl':'//www')+'.google-analytics.com/ga.js';
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>

563
developers/rest_api.html
View file

@ -1,562 +1 @@
<!doctype html>
<!--[if lt IE 7]> <html class="no-js lt-ie9 lt-ie8 lt-ie7"> <![endif]-->
<!--[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>Rest API - Home Assistant</title>
<meta name="author" content="Paulus Schoutsen">
<meta name="description" content="Home Assistant Rest API documentation">
<meta name="viewport" content="width=device-width">
<link rel="canonical" href="https://home-assistant.io/developers/rest_api.html">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="Rest API">
<meta property="og:site_name" content="Home Assistant">
<meta property="og:url" content="https://home-assistant.io/developers/rest_api.html">
<meta property="og:type" content="website">
<meta property="og:description" content="Home Assistant Rest API documentation">
<meta property="og:image" content="https://home-assistant.io/images/home-assistant-logo-2164x2164.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='/images/favicon-192x192.png'> Home Assistant
</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>
<ul>
<li><a href='/getting-started/'>Installing Home Assistant</a></li>
<li><a href='/getting-started/configuration.html'>Configuration basics</a></li>
<li><a href='/getting-started/devices.html'>Adding devices</a></li>
<li><a href='/getting-started/presence-detection.html'>Presence detection</a></li>
<li><a href='/getting-started/automation.html'>Automation</a></li>
<li><a href='/cookbook'>Configuration cookbook</a></li>
</ul>
</li>
<li><a href='/components/'>Components</a></li>
<li>
<a href="/developers/">Developers</a>
<ul>
<li><a href="/developers/architecture.html">Architecture</a></li>
<li><a href="/developers/frontend.html">Frontend development</a></li>
<li><a href="/developers/creating_components.html">
Creating components
</a></li>
<li><a href="/developers/add_new_platform.html">
Adding platform support
</a></li>
<li><a href="/developers/api.html">API</a></li>
<li><a href="/developers/credits.html">Credits</a></li>
</ul>
</li>
<li><a href="/blog/">Blog</a></li>
<li><a href="/help/">Need help?</a></li>
</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">
Rest API
</h1>
</header>
<hr class="divider">
<p>Home Assistant runs a web server accessible on port 8123.</p>
<ul>
<li><a href="http://localhost:8123/">http://localhost:8123/</a> is an interface to control Home Assistant.</li>
<li><a href="http://localhost:8123/api/">http://localhost:8123/api/</a> 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>X-HA-Access: YOUR_PASSWORD</code> (YOUR_PASSWORD as specified in your <code>configuration.yaml</code> file).</p>
<p>There are multiple ways to consume the Home Assistant Rest API. One is with <code>curl</code>:</p>
<figure class='code'><figcaption><span></span></figcaption><div class="highlight"><table><tr><td class="gutter"><pre class="line-numbers"><span class='line-number'>1</span>
<span class='line-number'>2</span>
<span class='line-number'>3</span>
</pre></td><td class='code'><pre><code class='bash'><span class='line'>curl -X GET <span class="se">\</span>
</span><span class='line'> -H <span class="s2">&quot;x-ha-access: YOUR_PASSWORD&quot;</span> <span class="se">\</span>
</span><span class='line'> http://localhost:8123/api/
</span></code></pre></td></tr></table></div></figure>
<p>Another option is to use Python and the <a href="http://docs.python-requests.org/en/latest/">Requests</a> module.</p>
<figure class='code'><figcaption><span></span></figcaption><div class="highlight"><table><tr><td class="gutter"><pre class="line-numbers"><span class='line-number'>1</span>
<span class='line-number'>2</span>
<span class='line-number'>3</span>
<span class='line-number'>4</span>
<span class='line-number'>5</span>
<span class='line-number'>6</span>
<span class='line-number'>7</span>
<span class='line-number'>8</span>
</pre></td><td class='code'><pre><code class='python'><span class='line'><span class="kn">from</span> <span class="nn">requests</span> <span class="kn">import</span> <span class="n">get</span>
</span><span class='line'>
</span><span class='line'><span class="n">url</span> <span class="o">=</span> <span class="s">&#39;http://localhost:8123/api/&#39;</span>
</span><span class='line'><span class="n">headers</span> <span class="o">=</span> <span class="p">{</span><span class="s">&#39;x-ha-access&#39;</span><span class="p">:</span> <span class="s">&#39;YOUR_PASSWORD&#39;</span><span class="p">,</span>
</span><span class='line'> <span class="s">&#39;content-type&#39;</span><span class="p">:</span> <span class="s">&#39;application/json&#39;</span><span class="p">}</span>
</span><span class='line'>
</span><span class='line'><span class="n">response</span> <span class="o">=</span> <span class="n">get</span><span class="p">(</span><span class="n">url</span><span class="p">,</span> <span class="n">headers</span><span class="o">=</span><span class="n">headers</span><span class="p">)</span>
</span><span class='line'><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>
</span></code></pre></td></tr></table></div></figure>
<p class='note'>
You can append <code>?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 message if API is up and running.</p>
<figure class='code'><figcaption><span></span></figcaption><div class="highlight"><table><tr><td class="gutter"><pre class="line-numbers"><span class='line-number'>1</span>
<span class='line-number'>2</span>
<span class='line-number'>3</span>
</pre></td><td class='code'><pre><code class='json'><span class='line'><span class="p">{</span>
</span><span class='line'> <span class="nt">&quot;message&quot;</span><span class="p">:</span> <span class="s2">&quot;API running.&quot;</span>
</span><span class='line'><span class="p">}</span>
</span></code></pre></td></tr></table></div></figure>
<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 contain event name and listener count.</p>
<figure class='code'><figcaption><span></span></figcaption><div class="highlight"><table><tr><td class="gutter"><pre class="line-numbers"><span class='line-number'>1</span>
<span class='line-number'>2</span>
<span class='line-number'>3</span>
<span class='line-number'>4</span>
<span class='line-number'>5</span>
<span class='line-number'>6</span>
<span class='line-number'>7</span>
<span class='line-number'>8</span>
<span class='line-number'>9</span>
<span class='line-number'>10</span>
</pre></td><td class='code'><pre><code class='json'><span class='line'><span class="p">[</span>
</span><span class='line'> <span class="p">{</span>
</span><span class='line'> <span class="nt">&quot;event&quot;</span><span class="p">:</span> <span class="s2">&quot;state_changed&quot;</span><span class="p">,</span>
</span><span class='line'> <span class="nt">&quot;listener_count&quot;</span><span class="p">:</span> <span class="mi">5</span>
</span><span class='line'> <span class="p">},</span>
</span><span class='line'> <span class="p">{</span>
</span><span class='line'> <span class="nt">&quot;event&quot;</span><span class="p">:</span> <span class="s2">&quot;time_changed&quot;</span><span class="p">,</span>
</span><span class='line'> <span class="nt">&quot;listener_count&quot;</span><span class="p">:</span> <span class="mi">2</span>
</span><span class='line'> <span class="p">}</span>
</span><span class='line'><span class="p">]</span>
</span></code></pre></td></tr></table></div></figure>
<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>
<figure class='code'><figcaption><span></span></figcaption><div class="highlight"><table><tr><td class="gutter"><pre class="line-numbers"><span class='line-number'>1</span>
<span class='line-number'>2</span>
<span class='line-number'>3</span>
<span class='line-number'>4</span>
<span class='line-number'>5</span>
<span class='line-number'>6</span>
<span class='line-number'>7</span>
<span class='line-number'>8</span>
<span class='line-number'>9</span>
<span class='line-number'>10</span>
<span class='line-number'>11</span>
<span class='line-number'>12</span>
<span class='line-number'>13</span>
<span class='line-number'>14</span>
<span class='line-number'>15</span>
</pre></td><td class='code'><pre><code class='json'><span class='line'><span class="p">[</span>
</span><span class='line'> <span class="p">{</span>
</span><span class='line'> <span class="nt">&quot;domain&quot;</span><span class="p">:</span> <span class="s2">&quot;browser&quot;</span><span class="p">,</span>
</span><span class='line'> <span class="nt">&quot;services&quot;</span><span class="p">:</span> <span class="p">[</span>
</span><span class='line'> <span class="s2">&quot;browse_url&quot;</span>
</span><span class='line'> <span class="p">]</span>
</span><span class='line'> <span class="p">},</span>
</span><span class='line'> <span class="p">{</span>
</span><span class='line'> <span class="nt">&quot;domain&quot;</span><span class="p">:</span> <span class="s2">&quot;keyboard&quot;</span><span class="p">,</span>
</span><span class='line'> <span class="nt">&quot;services&quot;</span><span class="p">:</span> <span class="p">[</span>
</span><span class='line'> <span class="s2">&quot;volume_up&quot;</span><span class="p">,</span>
</span><span class='line'> <span class="s2">&quot;volume_down&quot;</span>
</span><span class='line'> <span class="p">]</span>
</span><span class='line'> <span class="p">}</span>
</span><span class='line'><span class="p">]</span>
</span></code></pre></td></tr></table></div></figure>
<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>
<figure class='code'><figcaption><span></span></figcaption><div class="highlight"><table><tr><td class="gutter"><pre class="line-numbers"><span class='line-number'>1</span>
<span class='line-number'>2</span>
<span class='line-number'>3</span>
<span class='line-number'>4</span>
<span class='line-number'>5</span>
<span class='line-number'>6</span>
<span class='line-number'>7</span>
<span class='line-number'>8</span>
<span class='line-number'>9</span>
<span class='line-number'>10</span>
<span class='line-number'>11</span>
<span class='line-number'>12</span>
<span class='line-number'>13</span>
<span class='line-number'>14</span>
<span class='line-number'>15</span>
<span class='line-number'>16</span>
<span class='line-number'>17</span>
</pre></td><td class='code'><pre><code class='json'><span class='line'><span class="p">[</span>
</span><span class='line'> <span class="p">{</span>
</span><span class='line'> <span class="nt">&quot;attributes&quot;</span><span class="p">:</span> <span class="p">{</span>
</span><span class='line'> <span class="nt">&quot;next_rising&quot;</span><span class="p">:</span> <span class="s2">&quot;07:04:15 29-10-2013&quot;</span><span class="p">,</span>
</span><span class='line'> <span class="nt">&quot;next_setting&quot;</span><span class="p">:</span> <span class="s2">&quot;18:00:31 29-10-2013&quot;</span>
</span><span class='line'> <span class="p">},</span>
</span><span class='line'> <span class="nt">&quot;entity_id&quot;</span><span class="p">:</span> <span class="s2">&quot;sun.sun&quot;</span><span class="p">,</span>
</span><span class='line'> <span class="nt">&quot;last_changed&quot;</span><span class="p">:</span> <span class="s2">&quot;23:24:33 28-10-2013&quot;</span><span class="p">,</span>
</span><span class='line'> <span class="nt">&quot;state&quot;</span><span class="p">:</span> <span class="s2">&quot;below_horizon&quot;</span>
</span><span class='line'> <span class="p">},</span>
</span><span class='line'> <span class="p">{</span>
</span><span class='line'> <span class="nt">&quot;attributes&quot;</span><span class="p">:</span> <span class="p">{},</span>
</span><span class='line'> <span class="nt">&quot;entity_id&quot;</span><span class="p">:</span> <span class="s2">&quot;process.Dropbox&quot;</span><span class="p">,</span>
</span><span class='line'> <span class="nt">&quot;last_changed&quot;</span><span class="p">:</span> <span class="s2">&quot;23:24:33 28-10-2013&quot;</span><span class="p">,</span>
</span><span class='line'> <span class="nt">&quot;state&quot;</span><span class="p">:</span> <span class="s2">&quot;on&quot;</span>
</span><span class='line'> <span class="p">}</span>
</span><span class='line'><span class="p">]</span>
</span></code></pre></td></tr></table></div></figure>
<h4><a class='title-link' name='get-apistatesltentity_id' href='#get-apistatesltentity_id'></a> GET /api/states/&lt;entity_id></h4>
<p>Returns a state object for specified entity_id. Returns 404 if not found.</p>
<figure class='code'><figcaption><span></span></figcaption><div class="highlight"><table><tr><td class="gutter"><pre class="line-numbers"><span class='line-number'>1</span>
<span class='line-number'>2</span>
<span class='line-number'>3</span>
<span class='line-number'>4</span>
<span class='line-number'>5</span>
<span class='line-number'>6</span>
<span class='line-number'>7</span>
<span class='line-number'>8</span>
<span class='line-number'>9</span>
</pre></td><td class='code'><pre><code class='json'><span class='line'><span class="p">{</span>
</span><span class='line'> <span class="nt">&quot;attributes&quot;</span><span class="p">:</span> <span class="p">{</span>
</span><span class='line'> <span class="nt">&quot;next_rising&quot;</span><span class="p">:</span> <span class="s2">&quot;07:04:15 29-10-2013&quot;</span><span class="p">,</span>
</span><span class='line'> <span class="nt">&quot;next_setting&quot;</span><span class="p">:</span> <span class="s2">&quot;18:00:31 29-10-2013&quot;</span>
</span><span class='line'> <span class="p">},</span>
</span><span class='line'> <span class="nt">&quot;entity_id&quot;</span><span class="p">:</span> <span class="s2">&quot;sun.sun&quot;</span><span class="p">,</span>
</span><span class='line'> <span class="nt">&quot;last_changed&quot;</span><span class="p">:</span> <span class="s2">&quot;23:24:33 28-10-2013&quot;</span><span class="p">,</span>
</span><span class='line'> <span class="nt">&quot;state&quot;</span><span class="p">:</span> <span class="s2">&quot;below_horizon&quot;</span>
</span><span class='line'><span class="p">}</span>
</span></code></pre></td></tr></table></div></figure>
<h4><a class='title-link' name='post-apistatesltentity_id' href='#post-apistatesltentity_id'></a> POST /api/states/&lt;entity_id></h4>
<p>Updates or creates the current state of an entity.</p>
<p>Expects a JSON object that has atleast a state attribute:</p>
<figure class='code'><figcaption><span></span></figcaption><div class="highlight"><table><tr><td class="gutter"><pre class="line-numbers"><span class='line-number'>1</span>
<span class='line-number'>2</span>
<span class='line-number'>3</span>
<span class='line-number'>4</span>
<span class='line-number'>5</span>
<span class='line-number'>6</span>
<span class='line-number'>7</span>
</pre></td><td class='code'><pre><code class='json'><span class='line'><span class="p">{</span>
</span><span class='line'> <span class="nt">&quot;state&quot;</span><span class="p">:</span> <span class="s2">&quot;below_horizon&quot;</span><span class="p">,</span>
</span><span class='line'> <span class="nt">&quot;attributes&quot;</span><span class="p">:</span> <span class="p">{</span>
</span><span class='line'> <span class="nt">&quot;next_rising&quot;</span><span class="p">:</span> <span class="s2">&quot;07:04:15 29-10-2013&quot;</span><span class="p">,</span>
</span><span class='line'> <span class="nt">&quot;next_setting&quot;</span><span class="p">:</span> <span class="s2">&quot;18:00:31 29-10-2013&quot;</span>
</span><span class='line'> <span class="p">}</span>
</span><span class='line'><span class="p">}</span>
</span></code></pre></td></tr></table></div></figure>
<p>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>
<figure class='code'><figcaption><span></span></figcaption><div class="highlight"><table><tr><td class="gutter"><pre class="line-numbers"><span class='line-number'>1</span>
<span class='line-number'>2</span>
<span class='line-number'>3</span>
<span class='line-number'>4</span>
<span class='line-number'>5</span>
<span class='line-number'>6</span>
<span class='line-number'>7</span>
<span class='line-number'>8</span>
<span class='line-number'>9</span>
</pre></td><td class='code'><pre><code class='json'><span class='line'><span class="p">{</span>
</span><span class='line'> <span class="nt">&quot;attributes&quot;</span><span class="p">:</span> <span class="p">{</span>
</span><span class='line'> <span class="nt">&quot;next_rising&quot;</span><span class="p">:</span> <span class="s2">&quot;07:04:15 29-10-2013&quot;</span><span class="p">,</span>
</span><span class='line'> <span class="nt">&quot;next_setting&quot;</span><span class="p">:</span> <span class="s2">&quot;18:00:31 29-10-2013&quot;</span>
</span><span class='line'> <span class="p">},</span>
</span><span class='line'> <span class="nt">&quot;entity_id&quot;</span><span class="p">:</span> <span class="s2">&quot;weather.sun&quot;</span><span class="p">,</span>
</span><span class='line'> <span class="nt">&quot;last_changed&quot;</span><span class="p">:</span> <span class="s2">&quot;23:24:33 28-10-2013&quot;</span><span class="p">,</span>
</span><span class='line'> <span class="nt">&quot;state&quot;</span><span class="p">:</span> <span class="s2">&quot;below_horizon&quot;</span>
</span><span class='line'><span class="p">}</span>
</span></code></pre></td></tr></table></div></figure>
<h4><a class='title-link' name='post-apieventsltevent_type' href='#post-apieventsltevent_type'></a> POST /api/events/&lt;event_type></h4>
<p>Fires an event with event_type</p>
<p>You can pass an optional JSON object to be used as <code>event_data</code>.</p>
<figure class='code'><figcaption><span></span></figcaption><div class="highlight"><table><tr><td class="gutter"><pre class="line-numbers"><span class='line-number'>1</span>
<span class='line-number'>2</span>
<span class='line-number'>3</span>
</pre></td><td class='code'><pre><code class='json'><span class='line'><span class="p">{</span>
</span><span class='line'> <span class="nt">&quot;next_rising&quot;</span><span class="p">:</span> <span class="s2">&quot;18:00:31 29-10-2013&quot;</span>
</span><span class='line'><span class="p">}</span>
</span></code></pre></td></tr></table></div></figure>
<p>Returns a message if successful.</p>
<figure class='code'><figcaption><span></span></figcaption><div class="highlight"><table><tr><td class="gutter"><pre class="line-numbers"><span class='line-number'>1</span>
<span class='line-number'>2</span>
<span class='line-number'>3</span>
</pre></td><td class='code'><pre><code class='json'><span class='line'><span class="p">{</span>
</span><span class='line'> <span class="nt">&quot;message&quot;</span><span class="p">:</span> <span class="s2">&quot;Event download_file fired.&quot;</span>
</span><span class='line'><span class="p">}</span>
</span></code></pre></td></tr></table></div></figure>
<h4><a class='title-link' name='post-apiservicesltdomainltservice' href='#post-apiservicesltdomainltservice'></a> POST /api/services/&lt;domain>/&lt;service></h4>
<p>Calls a service within a specific domain. Will return when the service has been executed or 10 seconds has past, whichever comes first.</p>
<p>You can pass an optional JSON object to be used as <code>service_data</code>.</p>
<figure class='code'><figcaption><span></span></figcaption><div class="highlight"><table><tr><td class="gutter"><pre class="line-numbers"><span class='line-number'>1</span>
<span class='line-number'>2</span>
<span class='line-number'>3</span>
</pre></td><td class='code'><pre><code class='json'><span class='line'><span class="p">{</span>
</span><span class='line'> <span class="nt">&quot;entity_id&quot;</span><span class="p">:</span> <span class="s2">&quot;light.Ceiling&quot;</span>
</span><span class='line'><span class="p">}</span>
</span></code></pre></td></tr></table></div></figure>
<p>Returns a list of states that have changed while the service was being executed.</p>
<figure class='code'><figcaption><span></span></figcaption><div class="highlight"><table><tr><td class="gutter"><pre class="line-numbers"><span class='line-number'>1</span>
<span class='line-number'>2</span>
<span class='line-number'>3</span>
<span class='line-number'>4</span>
<span class='line-number'>5</span>
<span class='line-number'>6</span>
<span class='line-number'>7</span>
<span class='line-number'>8</span>
<span class='line-number'>9</span>
<span class='line-number'>10</span>
<span class='line-number'>11</span>
<span class='line-number'>12</span>
<span class='line-number'>13</span>
<span class='line-number'>14</span>
<span class='line-number'>15</span>
<span class='line-number'>16</span>
<span class='line-number'>17</span>
</pre></td><td class='code'><pre><code class='json'><span class='line'><span class="p">[</span>
</span><span class='line'> <span class="p">{</span>
</span><span class='line'> <span class="nt">&quot;attributes&quot;</span><span class="p">:</span> <span class="p">{</span>
</span><span class='line'> <span class="nt">&quot;next_rising&quot;</span><span class="p">:</span> <span class="s2">&quot;07:04:15 29-10-2013&quot;</span><span class="p">,</span>
</span><span class='line'> <span class="nt">&quot;next_setting&quot;</span><span class="p">:</span> <span class="s2">&quot;18:00:31 29-10-2013&quot;</span>
</span><span class='line'> <span class="p">},</span>
</span><span class='line'> <span class="nt">&quot;entity_id&quot;</span><span class="p">:</span> <span class="s2">&quot;sun.sun&quot;</span><span class="p">,</span>
</span><span class='line'> <span class="nt">&quot;last_changed&quot;</span><span class="p">:</span> <span class="s2">&quot;23:24:33 28-10-2013&quot;</span><span class="p">,</span>
</span><span class='line'> <span class="nt">&quot;state&quot;</span><span class="p">:</span> <span class="s2">&quot;below_horizon&quot;</span>
</span><span class='line'> <span class="p">},</span>
</span><span class='line'> <span class="p">{</span>
</span><span class='line'> <span class="nt">&quot;attributes&quot;</span><span class="p">:</span> <span class="p">{},</span>
</span><span class='line'> <span class="nt">&quot;entity_id&quot;</span><span class="p">:</span> <span class="s2">&quot;process.Dropbox&quot;</span><span class="p">,</span>
</span><span class='line'> <span class="nt">&quot;last_changed&quot;</span><span class="p">:</span> <span class="s2">&quot;23:24:33 28-10-2013&quot;</span><span class="p">,</span>
</span><span class='line'> <span class="nt">&quot;state&quot;</span><span class="p">:</span> <span class="s2">&quot;on&quot;</span>
</span><span class='line'> <span class="p">}</span>
</span><span class='line'><span class="p">]</span>
</span></code></pre></td></tr></table></div></figure>
<p class='note'>
The result will include any changed states that changed while the service was being executed, even if their change was the result of something else happening in the system.
</p>
<h4><a class='title-link' name='post-apievent_forwarding' href='#post-apievent_forwarding'></a> POST /api/event_forwarding</h4>
<p>Setup event forwarding to another Home Assistant instance.</p>
<p>Requires a JSON object that represents the API to forward to.</p>
<figure class='code'><figcaption><span></span></figcaption><div class="highlight"><table><tr><td class="gutter"><pre class="line-numbers"><span class='line-number'>1</span>
<span class='line-number'>2</span>
<span class='line-number'>3</span>
<span class='line-number'>4</span>
<span class='line-number'>5</span>
</pre></td><td class='code'><pre><code class='json'><span class='line'><span class="p">{</span>
</span><span class='line'> <span class="nt">&quot;host&quot;</span><span class="p">:</span> <span class="s2">&quot;machine&quot;</span><span class="p">,</span>
</span><span class='line'> <span class="nt">&quot;api_password&quot;</span><span class="p">:</span> <span class="s2">&quot;my_super_secret_password&quot;</span><span class="p">,</span>
</span><span class='line'> <span class="nt">&quot;port&quot;</span><span class="p">:</span> <span class="mi">8880</span> <span class="err">//</span> <span class="err">optional</span>
</span><span class='line'><span class="p">}</span>
</span></code></pre></td></tr></table></div></figure>
<p>It will return a message if event forwarding was setup successful.</p>
<figure class='code'><figcaption><span></span></figcaption><div class="highlight"><table><tr><td class="gutter"><pre class="line-numbers"><span class='line-number'>1</span>
<span class='line-number'>2</span>
<span class='line-number'>3</span>
</pre></td><td class='code'><pre><code class='json'><span class='line'><span class="p">{</span>
</span><span class='line'> <span class="nt">&quot;message&quot;</span><span class="p">:</span> <span class="s2">&quot;Event forwarding setup.&quot;</span>
</span><span class='line'><span class="p">}</span>
</span></code></pre></td></tr></table></div></figure>
<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>
<figure class='code'><figcaption><span></span></figcaption><div class="highlight"><table><tr><td class="gutter"><pre class="line-numbers"><span class='line-number'>1</span>
<span class='line-number'>2</span>
<span class='line-number'>3</span>
<span class='line-number'>4</span>
<span class='line-number'>5</span>
</pre></td><td class='code'><pre><code class='json'><span class='line'><span class="p">{</span>
</span><span class='line'> <span class="nt">&quot;host&quot;</span><span class="p">:</span> <span class="s2">&quot;machine&quot;</span><span class="p">,</span>
</span><span class='line'> <span class="nt">&quot;api_password&quot;</span><span class="p">:</span> <span class="s2">&quot;my_super_secret_password&quot;</span><span class="p">,</span>
</span><span class='line'> <span class="nt">&quot;port&quot;</span><span class="p">:</span> <span class="mi">8880</span> <span class="err">//</span> <span class="err">optional</span>
</span><span class='line'><span class="p">}</span>
</span></code></pre></td></tr></table></div></figure>
<p>It will return a message if event forwarding was cancelled successful.</p>
<figure class='code'><figcaption><span></span></figcaption><div class="highlight"><table><tr><td class="gutter"><pre class="line-numbers"><span class='line-number'>1</span>
<span class='line-number'>2</span>
<span class='line-number'>3</span>
</pre></td><td class='code'><pre><code class='json'><span class='line'><span class="p">{</span>
</span><span class='line'> <span class="nt">&quot;message&quot;</span><span class="p">:</span> <span class="s2">&quot;Event forwarding cancelled.&quot;</span>
</span><span class='line'><span class="p">}</span>
</span></code></pre></td></tr></table></div></figure>
<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>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item">
<p class="copyright">
<span class="credit">Powered by <a href="http://octopress.org">Octopress</a>, <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>. Hosted by <a href='https://pages.github.com/'>GitHub</a> and served by <a href='https://cloudflare.com'>CloudFlare</a>.</span>
</p>
</div>
</div>
</div>
</footer>
<!--[if lt IE 7]>
<p class="chromeframe">You are using an <strong>outdated</strong> browser. Please <a href="http://browsehappy.com/">upgrade your browser</a> or <a href="http://www.google.com/chromeframe/?redirect=true">activate Google Chrome Frame</a> to improve your experience.</p>
<![endif]-->
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
g.src=('https:'==location.protocol?'//ssl':'//www')+'.google-analytics.com/ga.js';
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>
<script>document.location = '/developers/rest_api/';</script>

437
developers/rest_api/index.html Normal file
View file

@ -0,0 +1,437 @@
<!doctype html>
<!--[if lt IE 7]> <html class="no-js lt-ie9 lt-ie8 lt-ie7"> <![endif]-->
<!--[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>Rest API - Home Assistant</title>
<meta name="author" content="Paulus Schoutsen">
<meta name="description" content="Home Assistant Rest 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="Rest API">
<meta property="og:site_name" content="Home Assistant">
<meta property="og:url" content="https://home-assistant.io/developers/rest_api/">
<meta property="og:type" content="website">
<meta property="og:description" content="Home Assistant Rest API documentation">
<meta property="og:image" content="https://home-assistant.io/images/home-assistant-logo-2164x2164.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='/images/favicon-192x192.png'> Home Assistant
</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>
<ul>
<li><a href='/getting-started/'>Installing Home Assistant</a></li>
<li><a href='/getting-started/configuration/'>Configuration basics</a></li>
<li><a href='/getting-started/devices/'>Adding devices</a></li>
<li><a href='/getting-started/presence-detection/'>Presence detection</a></li>
<li><a href='/getting-started/automation/'>Automation</a></li>
<li><a href='/cookbook'>Configuration cookbook</a></li>
</ul>
</li>
<li><a href='/components/'>Components</a></li>
<li>
<a href="/developers/">Developers</a>
<ul>
<li><a href="/developers/architecture/">Architecture</a></li>
<li><a href="/developers/frontend/">Frontend development</a></li>
<li><a href="/developers/creating_components/">
Creating components
</a></li>
<li><a href="/developers/add_new_platform/">
Adding platform support
</a></li>
<li><a href="/developers/api/">API</a></li>
<li><a href="/developers/credits/">Credits</a></li>
</ul>
</li>
<li><a href="/blog/">Blog</a></li>
<li><a href="/help/">Need help?</a></li>
</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">
Rest API
</h1>
</header>
<hr class="divider">
<p>Home Assistant runs a web server accessible on port 8123.</p>
<ul>
<li>http://localhost:8123/ is an interface to control Home Assistant.</li>
<li>http://localhost: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>X-HA-Access: YOUR_PASSWORD</code> (YOUR_PASSWORD as specified in your <code>configuration.yaml</code> file).</p>
<p>There are multiple ways to consume the Home Assistant Rest API. One is with <code>curl</code>:</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>curl -X GET \
-H &quot;x-ha-access: YOUR_PASSWORD&quot; \
http://localhost:8123/api/
</pre></div>
</div>
</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="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre><span class="keyword">from</span> <span class="include">requests</span> <span class="keyword">import</span> <span class="include">get</span>
url = <span class="string"><span class="delimiter">'</span><span class="content">http://localhost:8123/api/</span><span class="delimiter">'</span></span>
headers = {<span class="string"><span class="delimiter">'</span><span class="content">x-ha-access</span><span class="delimiter">'</span></span>: <span class="string"><span class="delimiter">'</span><span class="content">YOUR_PASSWORD</span><span class="delimiter">'</span></span>,
<span class="string"><span class="delimiter">'</span><span class="content">content-type</span><span class="delimiter">'</span></span>: <span class="string"><span class="delimiter">'</span><span class="content">application/json</span><span class="delimiter">'</span></span>}
response = get(url, headers=headers)
print(response.text)
</pre></div>
</div>
</div>
<p class="note">
You can append <code>?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 message if API is up and running.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>{
<span class="key"><span class="delimiter">&quot;</span><span class="content">message</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">API running.</span><span class="delimiter">&quot;</span></span>
}
</pre></div>
</div>
</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 contain event name and listener count.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>[
{
<span class="key"><span class="delimiter">&quot;</span><span class="content">event</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">state_changed</span><span class="delimiter">&quot;</span></span>,
<span class="key"><span class="delimiter">&quot;</span><span class="content">listener_count</span><span class="delimiter">&quot;</span></span>: <span class="integer">5</span>
},
{
<span class="key"><span class="delimiter">&quot;</span><span class="content">event</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">time_changed</span><span class="delimiter">&quot;</span></span>,
<span class="key"><span class="delimiter">&quot;</span><span class="content">listener_count</span><span class="delimiter">&quot;</span></span>: <span class="integer">2</span>
}
]
</pre></div>
</div>
</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="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>[
{
<span class="key"><span class="delimiter">&quot;</span><span class="content">domain</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">browser</span><span class="delimiter">&quot;</span></span>,
<span class="key"><span class="delimiter">&quot;</span><span class="content">services</span><span class="delimiter">&quot;</span></span>: [
<span class="string"><span class="delimiter">&quot;</span><span class="content">browse_url</span><span class="delimiter">&quot;</span></span>
]
},
{
<span class="key"><span class="delimiter">&quot;</span><span class="content">domain</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">keyboard</span><span class="delimiter">&quot;</span></span>,
<span class="key"><span class="delimiter">&quot;</span><span class="content">services</span><span class="delimiter">&quot;</span></span>: [
<span class="string"><span class="delimiter">&quot;</span><span class="content">volume_up</span><span class="delimiter">&quot;</span></span>,
<span class="string"><span class="delimiter">&quot;</span><span class="content">volume_down</span><span class="delimiter">&quot;</span></span>
]
}
]
</pre></div>
</div>
</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="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>[
{
<span class="key"><span class="delimiter">&quot;</span><span class="content">attributes</span><span class="delimiter">&quot;</span></span>: {
<span class="key"><span class="delimiter">&quot;</span><span class="content">next_rising</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">07:04:15 29-10-2013</span><span class="delimiter">&quot;</span></span>,
<span class="key"><span class="delimiter">&quot;</span><span class="content">next_setting</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">18:00:31 29-10-2013</span><span class="delimiter">&quot;</span></span>
},
<span class="key"><span class="delimiter">&quot;</span><span class="content">entity_id</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">sun.sun</span><span class="delimiter">&quot;</span></span>,
<span class="key"><span class="delimiter">&quot;</span><span class="content">last_changed</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">23:24:33 28-10-2013</span><span class="delimiter">&quot;</span></span>,
<span class="key"><span class="delimiter">&quot;</span><span class="content">state</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">below_horizon</span><span class="delimiter">&quot;</span></span>
},
{
<span class="key"><span class="delimiter">&quot;</span><span class="content">attributes</span><span class="delimiter">&quot;</span></span>: {},
<span class="key"><span class="delimiter">&quot;</span><span class="content">entity_id</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">process.Dropbox</span><span class="delimiter">&quot;</span></span>,
<span class="key"><span class="delimiter">&quot;</span><span class="content">last_changed</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">23:24:33 28-10-2013</span><span class="delimiter">&quot;</span></span>,
<span class="key"><span class="delimiter">&quot;</span><span class="content">state</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">on</span><span class="delimiter">&quot;</span></span>
}
]
</pre></div>
</div>
</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="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>{
<span class="key"><span class="delimiter">&quot;</span><span class="content">attributes</span><span class="delimiter">&quot;</span></span>: {
<span class="key"><span class="delimiter">&quot;</span><span class="content">next_rising</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">07:04:15 29-10-2013</span><span class="delimiter">&quot;</span></span>,
<span class="key"><span class="delimiter">&quot;</span><span class="content">next_setting</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">18:00:31 29-10-2013</span><span class="delimiter">&quot;</span></span>
},
<span class="key"><span class="delimiter">&quot;</span><span class="content">entity_id</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">sun.sun</span><span class="delimiter">&quot;</span></span>,
<span class="key"><span class="delimiter">&quot;</span><span class="content">last_changed</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">23:24:33 28-10-2013</span><span class="delimiter">&quot;</span></span>,
<span class="key"><span class="delimiter">&quot;</span><span class="content">state</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">below_horizon</span><span class="delimiter">&quot;</span></span>
}
</pre></div>
</div>
</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 atleast a state attribute:</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>{
<span class="key"><span class="delimiter">&quot;</span><span class="content">state</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">below_horizon</span><span class="delimiter">&quot;</span></span>,
<span class="key"><span class="delimiter">&quot;</span><span class="content">attributes</span><span class="delimiter">&quot;</span></span>: {
<span class="key"><span class="delimiter">&quot;</span><span class="content">next_rising</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">07:04:15 29-10-2013</span><span class="delimiter">&quot;</span></span>,
<span class="key"><span class="delimiter">&quot;</span><span class="content">next_setting</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">18:00:31 29-10-2013</span><span class="delimiter">&quot;</span></span>
}
}
</pre></div>
</div>
</div>
<p>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="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>{
<span class="key"><span class="delimiter">&quot;</span><span class="content">attributes</span><span class="delimiter">&quot;</span></span>: {
<span class="key"><span class="delimiter">&quot;</span><span class="content">next_rising</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">07:04:15 29-10-2013</span><span class="delimiter">&quot;</span></span>,
<span class="key"><span class="delimiter">&quot;</span><span class="content">next_setting</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">18:00:31 29-10-2013</span><span class="delimiter">&quot;</span></span>
},
<span class="key"><span class="delimiter">&quot;</span><span class="content">entity_id</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">weather.sun</span><span class="delimiter">&quot;</span></span>,
<span class="key"><span class="delimiter">&quot;</span><span class="content">last_changed</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">23:24:33 28-10-2013</span><span class="delimiter">&quot;</span></span>,
<span class="key"><span class="delimiter">&quot;</span><span class="content">state</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">below_horizon</span><span class="delimiter">&quot;</span></span>
}
</pre></div>
</div>
</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>event_data</code>.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>{
<span class="key"><span class="delimiter">&quot;</span><span class="content">next_rising</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">18:00:31 29-10-2013</span><span class="delimiter">&quot;</span></span>
}
</pre></div>
</div>
</div>
<p>Returns a message if successful.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>{
<span class="key"><span class="delimiter">&quot;</span><span class="content">message</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">Event download_file fired.</span><span class="delimiter">&quot;</span></span>
}
</pre></div>
</div>
</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 10 seconds has past, whichever comes first.</p>
<p>You can pass an optional JSON object to be used as <code>service_data</code>.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>{
<span class="key"><span class="delimiter">&quot;</span><span class="content">entity_id</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">light.Ceiling</span><span class="delimiter">&quot;</span></span>
}
</pre></div>
</div>
</div>
<p>Returns a list of states that have changed while the service was being executed.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>[
{
<span class="key"><span class="delimiter">&quot;</span><span class="content">attributes</span><span class="delimiter">&quot;</span></span>: {
<span class="key"><span class="delimiter">&quot;</span><span class="content">next_rising</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">07:04:15 29-10-2013</span><span class="delimiter">&quot;</span></span>,
<span class="key"><span class="delimiter">&quot;</span><span class="content">next_setting</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">18:00:31 29-10-2013</span><span class="delimiter">&quot;</span></span>
},
<span class="key"><span class="delimiter">&quot;</span><span class="content">entity_id</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">sun.sun</span><span class="delimiter">&quot;</span></span>,
<span class="key"><span class="delimiter">&quot;</span><span class="content">last_changed</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">23:24:33 28-10-2013</span><span class="delimiter">&quot;</span></span>,
<span class="key"><span class="delimiter">&quot;</span><span class="content">state</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">below_horizon</span><span class="delimiter">&quot;</span></span>
},
{
<span class="key"><span class="delimiter">&quot;</span><span class="content">attributes</span><span class="delimiter">&quot;</span></span>: {},
<span class="key"><span class="delimiter">&quot;</span><span class="content">entity_id</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">process.Dropbox</span><span class="delimiter">&quot;</span></span>,
<span class="key"><span class="delimiter">&quot;</span><span class="content">last_changed</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">23:24:33 28-10-2013</span><span class="delimiter">&quot;</span></span>,
<span class="key"><span class="delimiter">&quot;</span><span class="content">state</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">on</span><span class="delimiter">&quot;</span></span>
}
]
</pre></div>
</div>
</div>
<p class="note">
The result will include any changed states that changed while the service was being executed, even if their change was the result of something else happening in the system.
</p>
<h4><a class="title-link" name="post-apievent_forwarding" href="#post-apievent_forwarding"></a> POST /api/event_forwarding</h4>
<p>Setup event forwarding to another Home Assistant instance.</p>
<p>Requires a JSON object that represents the API to forward to.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>{
<span class="key"><span class="delimiter">&quot;</span><span class="content">host</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">machine</span><span class="delimiter">&quot;</span></span>,
<span class="key"><span class="delimiter">&quot;</span><span class="content">api_password</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">my_super_secret_password</span><span class="delimiter">&quot;</span></span>,
<span class="key"><span class="delimiter">&quot;</span><span class="content">port</span><span class="delimiter">&quot;</span></span>: <span class="integer">8880</span> <span class="error">/</span><span class="error">/</span> <span class="error">o</span><span class="error">p</span><span class="error">t</span><span class="error">i</span><span class="error">o</span><span class="error">n</span><span class="error">a</span><span class="error">l</span>
}
</pre></div>
</div>
</div>
<p>It will return a message if event forwarding was setup successful.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>{
<span class="key"><span class="delimiter">&quot;</span><span class="content">message</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">Event forwarding setup.</span><span class="delimiter">&quot;</span></span>
}
</pre></div>
</div>
</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="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>{
<span class="key"><span class="delimiter">&quot;</span><span class="content">host</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">machine</span><span class="delimiter">&quot;</span></span>,
<span class="key"><span class="delimiter">&quot;</span><span class="content">api_password</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">my_super_secret_password</span><span class="delimiter">&quot;</span></span>,
<span class="key"><span class="delimiter">&quot;</span><span class="content">port</span><span class="delimiter">&quot;</span></span>: <span class="integer">8880</span> <span class="error">/</span><span class="error">/</span> <span class="error">o</span><span class="error">p</span><span class="error">t</span><span class="error">i</span><span class="error">o</span><span class="error">n</span><span class="error">a</span><span class="error">l</span>
}
</pre></div>
</div>
</div>
<p>It will return a message if event forwarding was cancelled successful.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>{
<span class="key"><span class="delimiter">&quot;</span><span class="content">message</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">Event forwarding cancelled.</span><span class="delimiter">&quot;</span></span>
}
</pre></div>
</div>
</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>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item">
<p class="copyright">
<span class="credit">Powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>. Hosted by <a href='https://pages.github.com/'>GitHub</a> and served by <a href='https://cloudflare.com'>CloudFlare</a>.</span>
</p>
</div>
</div>
</div>
</footer>
<!--[if lt IE 7]>
<p class="chromeframe">You are using an <strong>outdated</strong> browser. Please <a href="http://browsehappy.com/">upgrade your browser</a> or <a href="http://www.google.com/chromeframe/?redirect=true">activate Google Chrome Frame</a> to improve your experience.</p>
<![endif]-->
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
g.src=('https:'==location.protocol?'//ssl':'//www')+'.google-analytics.com/ga.js';
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>

206
developers/website.html
View file

@ -1,205 +1 @@
<!doctype html>
<!--[if lt IE 7]> <html class="no-js lt-ie9 lt-ie8 lt-ie7"> <![endif]-->
<!--[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="Paulus Schoutsen">
<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.html">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="Website home-assistant.io">
<meta property="og:site_name" content="Home Assistant">
<meta property="og:url" content="https://home-assistant.io/developers/website.html">
<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/home-assistant-logo-2164x2164.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='/images/favicon-192x192.png'> Home Assistant
</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>
<ul>
<li><a href='/getting-started/'>Installing Home Assistant</a></li>
<li><a href='/getting-started/configuration.html'>Configuration basics</a></li>
<li><a href='/getting-started/devices.html'>Adding devices</a></li>
<li><a href='/getting-started/presence-detection.html'>Presence detection</a></li>
<li><a href='/getting-started/automation.html'>Automation</a></li>
<li><a href='/cookbook'>Configuration cookbook</a></li>
</ul>
</li>
<li><a href='/components/'>Components</a></li>
<li>
<a href="/developers/">Developers</a>
<ul>
<li><a href="/developers/architecture.html">Architecture</a></li>
<li><a href="/developers/frontend.html">Frontend development</a></li>
<li><a href="/developers/creating_components.html">
Creating components
</a></li>
<li><a href="/developers/add_new_platform.html">
Adding platform support
</a></li>
<li><a href="/developers/api.html">API</a></li>
<li><a href="/developers/credits.html">Credits</a></li>
</ul>
</li>
<li><a href="/blog/">Blog</a></li>
<li><a href="/help/">Need help?</a></li>
</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 home of Home Assistant is <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 using <a href="http://octopress.org/">Octopress</a>. To get more details, please checkout the <a href="http://octopress.org/docs/">documentation</a>. That means that creating a new page is simple. The pages are written in <a href="http://daringfireball.net/projects/markdown/">markdown</a>, you don&rsquo;t need to care about HTML or alike.</p>
<p>To work on the website the process is no different to working on Home Assistant itself.</p>
<ul>
<li>Fork the home-assistant.io <a href="https://github.com/balloob/home-assistant.io">git repository</a>.</li>
<li>Create/edit/update a page.</li>
<li>To test changes to home-assistant.io locally, run <code>rake preview</code> and navigate to <a href="http://127.0.0.1:4000.">http://127.0.0.1:4000.</a></li>
<li>Create a Pull Request against the <strong>master</strong> branch of home-assistant.io.</li>
</ul>
<p>For a component page it would be the fastest way to make a copy of an existing page and edit it.</p>
<h2>Code</h2>
<p>To take advantage of the build-in features of Octopress to display code snipplets, just use the default markdown syntax.</p>
<figure class='code'><figcaption><span></span></figcaption><div class="highlight"><table><tr><td class="gutter"><pre class="line-numbers"><span class='line-number'>1</span>
</pre></td><td class='code'><pre><code class='bash'><span class='line'>Here goes the code...
</span></code></pre></td></tr></table></div></figure>
<h2>Images, icons, and logos</h2>
<p>The images which are displayed on the pages are stored in various directories according their purpose.</p>
<table>
<thead>
<tr>
<th style="text-align:left;"> Type </th>
<th style="text-align:left;"> Location </th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align:left;"> screen shots </td>
<td style="text-align:left;"> source/images/screenshots </td>
</tr>
<tr>
<td style="text-align:left;"> logos </td>
<td style="text-align:left;"> source/images/supported_brands </td>
</tr>
</tbody>
</table>
<p>Not everything (product, component, etc.) has a logo, to show something we are using the <a href="http://ftp.gnome.org/pub/GNOME/sources/gnome-icon-theme">Gnome Icon Theme</a> from the <a href="http://www.gnome.org">GNOME Project</a> as a source for the placeholders. Those icons are licensed under the GNU LGPL v.3 or Creative Commons BY-SA 3.0 license.</p>
</article>
</div>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item">
<p class="copyright">
<span class="credit">Powered by <a href="http://octopress.org">Octopress</a>, <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>. Hosted by <a href='https://pages.github.com/'>GitHub</a> and served by <a href='https://cloudflare.com'>CloudFlare</a>.</span>
</p>
</div>
</div>
</div>
</footer>
<!--[if lt IE 7]>
<p class="chromeframe">You are using an <strong>outdated</strong> browser. Please <a href="http://browsehappy.com/">upgrade your browser</a> or <a href="http://www.google.com/chromeframe/?redirect=true">activate Google Chrome Frame</a> to improve your experience.</p>
<![endif]-->
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
g.src=('https:'==location.protocol?'//ssl':'//www')+'.google-analytics.com/ga.js';
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>
<script>document.location = '/developers/website/';</script>

189
developers/website/index.html Normal file
View file

@ -0,0 +1,189 @@
<!doctype html>
<!--[if lt IE 7]> <html class="no-js lt-ie9 lt-ie8 lt-ie7"> <![endif]-->
<!--[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="Paulus Schoutsen">
<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">
<meta property="og:url" content="https://home-assistant.io/developers/website/">
<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/home-assistant-logo-2164x2164.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='/images/favicon-192x192.png'> Home Assistant
</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>
<ul>
<li><a href='/getting-started/'>Installing Home Assistant</a></li>
<li><a href='/getting-started/configuration/'>Configuration basics</a></li>
<li><a href='/getting-started/devices/'>Adding devices</a></li>
<li><a href='/getting-started/presence-detection/'>Presence detection</a></li>
<li><a href='/getting-started/automation/'>Automation</a></li>
<li><a href='/cookbook'>Configuration cookbook</a></li>
</ul>
</li>
<li><a href='/components/'>Components</a></li>
<li>
<a href="/developers/">Developers</a>
<ul>
<li><a href="/developers/architecture/">Architecture</a></li>
<li><a href="/developers/frontend/">Frontend development</a></li>
<li><a href="/developers/creating_components/">
Creating components
</a></li>
<li><a href="/developers/add_new_platform/">
Adding platform support
</a></li>
<li><a href="/developers/api/">API</a></li>
<li><a href="/developers/credits/">Credits</a></li>
</ul>
</li>
<li><a href="/blog/">Blog</a></li>
<li><a href="/help/">Need help?</a></li>
</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 home of Home Assistant is <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 using <a href="http://octopress.org/">Octopress</a>. To get more details, please checkout the <a href="http://octopress.org/docs/">documentation</a>. That means that creating a new page is simple. The pages are written in <a href="http://daringfireball.net/projects/markdown/">markdown</a>, you don’t need to care about HTML or alike.</p>
<p>To work on the website the process is no different to working on Home Assistant itself.</p>
<ul>
<li>Fork the home-assistant.io <a href="https://github.com/balloob/home-assistant.io">git repository</a>.</li>
<li>Create/edit/update a page.</li>
<li>To test changes to home-assistant.io locally, run <code>rake preview</code> and navigate to http://127.0.0.1:4000.</li>
<li>Create a Pull Request against the <strong>master</strong> branch of home-assistant.io.</li>
</ul>
<p>For a component page it would be the fastest way to make a copy of an existing page and edit it.</p>
<h2>Code</h2>
<p>To take advantage of the build-in features of Octopress to display code snipplets, just use the default markdown syntax.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>Here goes the code...
</pre></div>
</div>
</div>
<h2>Images, icons, and logos</h2>
<p>The images which are displayed on the pages are stored in various directories according their purpose.</p>
<table>
<thead>
<tr>
<th style="text-align: left">Type</th>
<th style="text-align: left">Location</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align: left">screen shots</td>
<td style="text-align: left">source/images/screenshots</td>
</tr>
<tr>
<td style="text-align: left">logos</td>
<td style="text-align: left">source/images/supported_brands</td>
</tr>
</tbody>
</table>
<p>Not everything (product, component, etc.) has a logo, to show something we are using the <a href="http://ftp.gnome.org/pub/GNOME/sources/gnome-icon-theme">Gnome Icon Theme</a> from the <a href="http://www.gnome.org">GNOME Project</a> as a source for the placeholders. Those icons are licensed under the GNU LGPL v.3 or Creative Commons BY-SA 3.0 license.</p>
</article>
</div>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item">
<p class="copyright">
<span class="credit">Powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>. Hosted by <a href='https://pages.github.com/'>GitHub</a> and served by <a href='https://cloudflare.com'>CloudFlare</a>.</span>
</p>
</div>
</div>
</div>
</footer>
<!--[if lt IE 7]>
<p class="chromeframe">You are using an <strong>outdated</strong> browser. Please <a href="http://browsehappy.com/">upgrade your browser</a> or <a href="http://www.google.com/chromeframe/?redirect=true">activate Google Chrome Frame</a> to improve your experience.</p>
<![endif]-->
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
g.src=('https:'==location.protocol?'//ssl':'//www')+'.google-analytics.com/ga.js';
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>