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

Site updated at 2016-07-24 17:14:05 UTC

Browse source
This commit is contained in:
Travis CI 2016-07-24 17:14:05 +00:00
parent 7010fdbc41
commit 2d9a218a1b
1007 changed files with 140 additions and 168343 deletions
Download patch file Download diff file Expand all files Collapse all files

294
topics/events/index.html
View file

@ -1,294 +0,0 @@
<!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>Events - Home Assistant</title>
<meta name="author" content="Home Assistant">
<meta name="description" content="Describes all there is to know about events in Home Assistant.">
<meta name="viewport" content="width=device-width">
<link rel="canonical" href="https://home-assistant.io/topics/events/">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="Events">
<meta property="og:site_name" content="Home Assistant">
<meta property="og:url" content="https://home-assistant.io/topics/events/">
<meta property="og:type" content="article">
<meta property="og:description" content="Describes all there is to know about events in Home Assistant.">
<meta property="og:image" content="https://home-assistant.io/images/default-social.png">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@home_assistant">
<meta name="twitter:title" content="Events">
<meta name="twitter:description" content="Describes all there is to know about events in Home Assistant.">
<meta name="twitter:image" content="https://home-assistant.io/images/default-social.png">
<link href="/stylesheets/screen.css" media="screen, projection" rel="stylesheet">
<link href="/atom.xml" rel="alternate" title="Home Assistant" type="application/atom+xml">
<link rel='shortcut icon' href='/images/favicon.ico' />
<link rel='icon' type='image/png' href='/images/favicon-192x192.png' sizes='192x192' />
</head>
<body >
<header>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item three-tenths lap-two-sixths palm-one-whole ha-title">
<a href="/" class="site-title">
<img width='40' src='/demo/favicon-192x192.png'>
<span>Home Assistant</span>
</a>
</div>
<div class="grid__item seven-tenths lap-four-sixths palm-one-whole">
<nav>
<input type="checkbox" id="toggle">
<label for="toggle" class="toggle" data-open="Main Menu" data-close="Close Menu"></label>
<ul class="menu pull-right">
<li><a href='/getting-started/'>Getting started</a></li>
<li><a href='/components/'>Components</a></li>
<li><a href='/cookbook/'>Examples</a></li>
<li><a href="/developers/">Developers</a></li>
<li><a href="/blog/">Blog</a></li>
<li><a href="/help/">Need help?</a></li>
</ul>
</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">
<div class='edit-github'><a href='https://github.com/home-assistant/home-assistant.io/tree/master/source/_topics/events.markdown'>Edit this page on GitHub</a></div>
<header>
<h1 class="title indent">
Events
</h1>
</header>
<hr class="divider">
<p>The core of Home Assistant is the event bus. The event bus allows any component to fire or listen for events. It is the core of everything. For example, any state change will be announced on the event bus as a <code>state_changed</code> event containing the previous and the new state of an entity.</p>
<p>Home Assistant contains a few built-in events that are used to coordinate between various components.</p>
<h3><a class="title-link" name="event-homeassistant_start" href="#event-homeassistant_start"></a> Event <code>homeassistant_start</code></h3>
<p>Event <code>homeassistant_start</code> is fired when all components from the configuration have been intitialized. This is the event that will start the timer firing off <code>time_changed</code> events.</p>
<h3><a class="title-link" name="event-homeassistant_stop" href="#event-homeassistant_stop"></a> Event <code>homeassistant_stop</code></h3>
<p>Event <code>homeassistant_stop</code> is fired when Home Assistant is shutting down. It should be used to close any open connection or release any resources.</p>
<h3><a class="title-link" name="event-state_changed" href="#event-state_changed"></a> Event <code>state_changed</code></h3>
<p>Event <code>state_changed</code> is fired when a state changes. Both <code>old_state</code> and <code>new_state</code> are state objects. <a href="/topics/state_object/">Documentation about state objects.</a></p>
<table>
<thead>
<tr>
<th>Field</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>entity_id</code></td>
<td>Entity ID of the changed entity. Example: <code>light.kitchen</code></td>
</tr>
<tr>
<td><code>old_state</code></td>
<td>The previous state of the entity before it changed. This field is ommitted if the entity is new.</td>
</tr>
<tr>
<td><code>new_state</code></td>
<td>The new state of the entity. This field is ommitted if the entity is removed from the state machine.</td>
</tr>
</tbody>
</table>
<h3><a class="title-link" name="event-time_changed" href="#event-time_changed"></a> Event <code>time_changed</code></h3>
<p>Event <code>time_changed</code> is fired every second by the timer and contains the current time.</p>
<table>
<thead>
<tr>
<th>Field</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>now</code></td>
<td>A <a href="https://docs.python.org/3.4/library/datetime.html#datetime.datetime">datetime object</a> containing the current time in UTC.</td>
</tr>
</tbody>
</table>
<h3><a class="title-link" name="event-service_registered" href="#event-service_registered"></a> Event <code>service_registered</code></h3>
<p>Event <code>service_registered</code> is fired when a new service has been registered within Home Assistant.</p>
<table>
<thead>
<tr>
<th>Field</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>domain</code></td>
<td>Domain of the service. Example: <code>light</code>.</td>
</tr>
<tr>
<td><code>service</code></td>
<td>The service to call. Example: <code>turn_on</code></td>
</tr>
</tbody>
</table>
<h3><a class="title-link" name="event-call_service" href="#event-call_service"></a> Event <code>call_service</code></h3>
<p>Event <code>call_service</code> is fired to call a service.</p>
<table>
<thead>
<tr>
<th>Field</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>domain</code></td>
<td>Domain of the service. Example: <code>light</code>.</td>
</tr>
<tr>
<td><code>service</code></td>
<td>The service to call. Example: <code>turn_on</code></td>
</tr>
<tr>
<td><code>service_data</code></td>
<td>Dictionary with the service call parameters. Example: <code>{ 'brightness': 120 }</code>.</td>
</tr>
<tr>
<td><code>service_call_id</code></td>
<td>String with a unique call id. Example: <code>23123-4</code>.</td>
</tr>
</tbody>
</table>
<h3><a class="title-link" name="event-service_executed" href="#event-service_executed"></a> Event <code>service_executed</code></h3>
<p>Event <code>service_executed</code> is fired by the service handler to indicate the service is done.</p>
<table>
<thead>
<tr>
<th>Field</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>service_call_id</code></td>
<td>String with the unique call id of the service call that was executed. Example: <code>23123-4</code>.</td>
</tr>
</tbody>
</table>
<h3><a class="title-link" name="event-platform_discovered" href="#event-platform_discovered"></a> Event <code>platform_discovered</code></h3>
<p>Event <code>platform_discovered</code> is fired when a new platform has been discovered by the discovery component.</p>
<table>
<thead>
<tr>
<th>Field</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>service</code></td>
<td>The service that is discovered. Example: <code>zwave</code>.</td>
</tr>
<tr>
<td><code>discovered</code></td>
<td>Information that is discovered. Can be a dict, tuple etc. Example: <code>(192.168.1.10, 8889)</code>.</td>
</tr>
</tbody>
</table>
<h3><a class="title-link" name="event-component_loaded" href="#event-component_loaded"></a> Event <code>component_loaded</code></h3>
<p>Event <code>component_loaded</code> is fired when a new component has been loaded and initialized.</p>
<table>
<thead>
<tr>
<th>Field</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>component</code></td>
<td>Domain of the component that has just been initialized. Example: <code>light</code>.</td>
</tr>
</tbody>
</table>
</article>
</div>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item">
<div class="copyright">
<a rel="me" href='https://twitter.com/home_assistant'><i class="icon-twitter"></i></a>
<a rel="me" href='https://github.com/home-assistant/home-assistant'><i class="icon-github"></i></a>
<div class="credit">
Contact us at <a href='mailto:hello@home-assistant.io'>hello@home-assistant.io</a>.<br>
Website powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>.<br />
Hosted by <a href='https://pages.github.com/'>GitHub</a> and served by <a href='https://cloudflare.com'>CloudFlare</a>.
</div>
</div>
</div>
</div>
</div>
</footer>
<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>

154
topics/index.html
View file

@ -1,154 +0,0 @@
<!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>Advanced Topics - Home Assistant</title>
<meta name="author" content="Home Assistant">
<meta name="description" content="Documentation about the more advanced features in Home Assistant.">
<meta name="viewport" content="width=device-width">
<link rel="canonical" href="https://home-assistant.io/topics/">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="Advanced Topics">
<meta property="og:site_name" content="Home Assistant">
<meta property="og:url" content="https://home-assistant.io/topics/">
<meta property="og:type" content="website">
<meta property="og:description" content="Documentation about the more advanced features in Home Assistant.">
<meta property="og:image" content="https://home-assistant.io/images/default-social.png">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@home_assistant">
<meta name="twitter:title" content="Advanced Topics">
<meta name="twitter:description" content="Documentation about the more advanced features in Home Assistant.">
<meta name="twitter:image" content="https://home-assistant.io/images/default-social.png">
<link href="/stylesheets/screen.css" media="screen, projection" rel="stylesheet">
<link href="/atom.xml" rel="alternate" title="Home Assistant" type="application/atom+xml">
<link rel='shortcut icon' href='/images/favicon.ico' />
<link rel='icon' type='image/png' href='/images/favicon-192x192.png' sizes='192x192' />
</head>
<body >
<header>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item three-tenths lap-two-sixths palm-one-whole ha-title">
<a href="/" class="site-title">
<img width='40' src='/demo/favicon-192x192.png'>
<span>Home Assistant</span>
</a>
</div>
<div class="grid__item seven-tenths lap-four-sixths palm-one-whole">
<nav>
<input type="checkbox" id="toggle">
<label for="toggle" class="toggle" data-open="Main Menu" data-close="Close Menu"></label>
<ul class="menu pull-right">
<li><a href='/getting-started/'>Getting started</a></li>
<li><a href='/components/'>Components</a></li>
<li><a href='/cookbook/'>Examples</a></li>
<li><a href="/developers/">Developers</a></li>
<li><a href="/blog/">Blog</a></li>
<li><a href="/help/">Need help?</a></li>
</ul>
</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">
Advanced Topics
</h1>
</header>
<hr class="divider">
<p>Home Assistant is built from many small building blocks that together offer a powerful and customizable system. This page is a collection of the more advanced topics.</p>
<ul>
<li>
<p><a href="/topics/platform_options/">Entity component platform options</a></p>
</li>
<li>
<p><a href="/topics/events/">Events</a></p>
</li>
<li>
<p><a href="/topics/splitting_configuration/">Splitting up the configuration</a></p>
</li>
<li>
<p><a href="/topics/state_object/">State Objects</a></p>
</li>
<li>
<p><a href="/topics/secrets/">Storing secrets</a></p>
</li>
<li>
<p><a href="/topics/templating/">Templating</a></p>
</li>
</ul>
</article>
</div>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item">
<div class="copyright">
<a rel="me" href='https://twitter.com/home_assistant'><i class="icon-twitter"></i></a>
<a rel="me" href='https://github.com/home-assistant/home-assistant'><i class="icon-github"></i></a>
<div class="credit">
Contact us at <a href='mailto:hello@home-assistant.io'>hello@home-assistant.io</a>.<br>
Website powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>.<br />
Hosted by <a href='https://pages.github.com/'>GitHub</a> and served by <a href='https://cloudflare.com'>CloudFlare</a>.
</div>
</div>
</div>
</div>
</div>
</footer>
<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>

252
topics/platform_options/index.html
View file

@ -1,252 +0,0 @@
<!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>Entity component platform options - Home Assistant</title>
<meta name="author" content="Home Assistant">
<meta name="description" content="Shows how to customize polling interval for any component via configuration.yaml.">
<meta name="viewport" content="width=device-width">
<link rel="canonical" href="https://home-assistant.io/topics/platform_options/">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="Entity component platform options">
<meta property="og:site_name" content="Home Assistant">
<meta property="og:url" content="https://home-assistant.io/topics/platform_options/">
<meta property="og:type" content="article">
<meta property="og:description" content="Shows how to customize polling interval for any component via configuration.yaml.">
<meta property="og:image" content="https://home-assistant.io/images/default-social.png">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@home_assistant">
<meta name="twitter:title" content="Entity component platform options">
<meta name="twitter:description" content="Shows how to customize polling interval for any component via configuration.yaml.">
<meta name="twitter:image" content="https://home-assistant.io/images/default-social.png">
<link href="/stylesheets/screen.css" media="screen, projection" rel="stylesheet">
<link href="/atom.xml" rel="alternate" title="Home Assistant" type="application/atom+xml">
<link rel='shortcut icon' href='/images/favicon.ico' />
<link rel='icon' type='image/png' href='/images/favicon-192x192.png' sizes='192x192' />
</head>
<body >
<header>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item three-tenths lap-two-sixths palm-one-whole ha-title">
<a href="/" class="site-title">
<img width='40' src='/demo/favicon-192x192.png'>
<span>Home Assistant</span>
</a>
</div>
<div class="grid__item seven-tenths lap-four-sixths palm-one-whole">
<nav>
<input type="checkbox" id="toggle">
<label for="toggle" class="toggle" data-open="Main Menu" data-close="Close Menu"></label>
<ul class="menu pull-right">
<li><a href='/getting-started/'>Getting started</a></li>
<li><a href='/components/'>Components</a></li>
<li><a href='/cookbook/'>Examples</a></li>
<li><a href="/developers/">Developers</a></li>
<li><a href="/blog/">Blog</a></li>
<li><a href="/help/">Need help?</a></li>
</ul>
</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">
<div class='edit-github'><a href='https://github.com/home-assistant/home-assistant.io/tree/master/source/_topics/platform_options.markdown'>Edit this page on GitHub</a></div>
<header>
<h1 class="title indent">
Entity Component Platform Options
</h1>
</header>
<hr class="divider">
<p>Any component that is based on the entity component allows various extra options to be set per platform.</p>
<h3><a class="title-link" name="entity-namespace" href="#entity-namespace"></a> Entity namespace</h3>
<p>By setting an entity namespace, all entities will be prefixed with that namespace. That way <code>light.bathroom</code> can become <code>light.holiday_house_bathroom</code>.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre><span class="comment"># Example configuration.yaml entry</span>
<span class="key">light</span>:
<span class="key">platform</span>: <span class="string"><span class="content">hue</span></span>
<span class="key">entity_namespace</span>: <span class="string"><span class="content">holiday_house</span></span>
</pre></div>
</div>
</div>
<h3><a class="title-link" name="scan-interval" href="#scan-interval"></a> Scan Interval</h3>
<p>Platforms that require polling will be polled in an interval specified by the main component. For example a light will check every 30 seconds for a changed state. It is possible to overwrite this scan interval for any platform that is being polled by specifying a <code>scan_interval</code> config key. In the example below we setup the Philips Hue lights but tell Home Assistant to poll the devices every 10 seconds instead of the default 30 seconds.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre><span class="comment"># Example configuration.yaml entry to poll Hue lights every 10 seconds.</span>
<span class="key">light</span>:
<span class="key">platform</span>: <span class="string"><span class="content">hue</span></span>
<span class="key">scan_interval</span>: <span class="string"><span class="content">10</span></span>
</pre></div>
</div>
</div>
</article>
</div>
<aside id="sidebar" class="grid__item one-third lap-one-whole palm-one-whole">
<div class="grid">
<section class="aside-module grid__item one-whole lap-one-half">
<h1 class="title delta">About Home Assistant</h1>
<ul class="divided">
<li>
Home Assistant is an open-source home automation platform running on Python 3. Track and control all devices at home and automate control.
</li>
<li><a href='/getting-started/'>Get started with Home Assistant</a></li>
<li><a href='/demo/'>Try the online demo</a></li>
<li><a class="twitter-follow-button" href="https://twitter.com/Home_Assistant">Follow Home Assistant on Twitter</a></li>
</ul>
</section>
<script>!function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0];if(!d.getElementById(id)){js=d.createElement(s);js.id=id;js.async=true;js.src='//platform.twitter.com/widgets.js';fjs.parentNode.insertBefore(js,fjs);}}(document, 'script', 'twitter-wjs');</script>
<section class="sharing aside-module grid__item one-whole lap-one-half">
<h1 class="title delta">Share this post</h1>
<a href="//twitter.com/share"
class="twitter-share-button"
data-via="home_assistant"
data-related="home_assistant"
data-url="https://home-assistant.io/topics/platform_options/"
data-counturl="https://home-assistant.io/topics/platform_options/" >Tweet</a>
<div class="fb-share-button" style='top: -6px;'
data-href="https://home-assistant.io/topics/platform_options/"
data-layout="button_count">
</div>
<div class="g-plusone" data-size="standard"></div>
</section>
<script src="https://apis.google.com/js/platform.js" async defer></script>
<script>
window.fbAsyncInit = function() {
FB.init({appId: '338291289691179', xfbml: true, version: 'v2.2'});
};
(function(d, s, id){
var js, fjs = d.getElementsByTagName(s)[0];
if (d.getElementById(id)) {return;}
js = d.createElement(s); js.id = id; js.async = true;
js.src = "//connect.facebook.net/en_US/sdk.js";
fjs.parentNode.insertBefore(js, fjs);
}(document, 'script', 'facebook-jssdk'));
</script>
<section id="recent-posts" class="aside-module grid__item one-whole lap-one-half">
<h1 class="title delta">Recent Posts</h1>
<ul class="divided">
<li class="post">
<a href="/blog/2016/07/23/internet-of-things-data-exploration-with-jupyter-notebooks/">IoT Data Exploration with Jupyter Notebooks</a>
</li>
<li class="post">
<a href="/blog/2016/07/19/visualizing-your-iot-data/">Visualize your IoT data</a>
</li>
<li class="post">
<a href="/blog/2016/07/16/sqlalchemy-knx-join-simplisafe/">0.24: SQLAlchemy, KNX, Join by Joaoapps, and SimpliSafe.</a>
</li>
<li class="post">
<a href="/blog/2016/07/06/pocketchip-running-home-assistant/">PocketCHIP running Home Assistant</a>
</li>
<li class="post">
<a href="/blog/2016/07/01/envisalink-homematic-hdmi-cec-and-sony-bravia-tv/">0.23: Envisalink, Homematic, HDMI-CEC and Sony Bravia TV</a>
</li>
</ul>
</section>
</div>
</aside>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item">
<div class="copyright">
<a rel="me" href='https://twitter.com/home_assistant'><i class="icon-twitter"></i></a>
<a rel="me" href='https://github.com/home-assistant/home-assistant'><i class="icon-github"></i></a>
<div class="credit">
Contact us at <a href='mailto:hello@home-assistant.io'>hello@home-assistant.io</a>.<br>
Website powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>.<br />
Hosted by <a href='https://pages.github.com/'>GitHub</a> and served by <a href='https://cloudflare.com'>CloudFlare</a>.
</div>
</div>
</div>
</div>
</div>
</footer>
<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>

223
topics/secrets/index.html
View file

@ -1,223 +0,0 @@
<!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>Storing secrets - Home Assistant</title>
<meta name="author" content="Home Assistant">
<meta name="description" content="Storing secrets outside of your configuration.yaml.">
<meta name="viewport" content="width=device-width">
<link rel="canonical" href="https://home-assistant.io/topics/secrets/">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="Storing secrets">
<meta property="og:site_name" content="Home Assistant">
<meta property="og:url" content="https://home-assistant.io/topics/secrets/">
<meta property="og:type" content="article">
<meta property="og:description" content="Storing secrets outside of your configuration.yaml.">
<meta property="og:image" content="https://home-assistant.io/images/default-social.png">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@home_assistant">
<meta name="twitter:title" content="Storing secrets">
<meta name="twitter:description" content="Storing secrets outside of your configuration.yaml.">
<meta name="twitter:image" content="https://home-assistant.io/images/default-social.png">
<link href="/stylesheets/screen.css" media="screen, projection" rel="stylesheet">
<link href="/atom.xml" rel="alternate" title="Home Assistant" type="application/atom+xml">
<link rel='shortcut icon' href='/images/favicon.ico' />
<link rel='icon' type='image/png' href='/images/favicon-192x192.png' sizes='192x192' />
</head>
<body >
<header>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item three-tenths lap-two-sixths palm-one-whole ha-title">
<a href="/" class="site-title">
<img width='40' src='/demo/favicon-192x192.png'>
<span>Home Assistant</span>
</a>
</div>
<div class="grid__item seven-tenths lap-four-sixths palm-one-whole">
<nav>
<input type="checkbox" id="toggle">
<label for="toggle" class="toggle" data-open="Main Menu" data-close="Close Menu"></label>
<ul class="menu pull-right">
<li><a href='/getting-started/'>Getting started</a></li>
<li><a href='/components/'>Components</a></li>
<li><a href='/cookbook/'>Examples</a></li>
<li><a href="/developers/">Developers</a></li>
<li><a href="/blog/">Blog</a></li>
<li><a href="/help/">Need help?</a></li>
</ul>
</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">
<div class='edit-github'><a href='https://github.com/home-assistant/home-assistant.io/tree/master/source/_topics/secrets.markdown'>Edit this page on GitHub</a></div>
<header>
<h1 class="title indent">
Storing Secrets
</h1>
</header>
<hr class="divider">
<p>The <code>configuration.yaml</code> file a plain-text file thus it is readable for everyone who has access to the file. The file contains passwords and API tokens which need to be redacted if you want to share your configuration. This separation can also help you to keep easier track of your passwords and API keys (as they are all stored at one place and no longer spread across the <code>configuration.yaml</code> file) if you don’t want to <a href="/topics/splitting_configuration/">split up your configuration</a>.</p>
<h3><a class="title-link" name="using-secretsyaml" href="#using-secretsyaml"></a> Using secrets.yaml</h3>
<p>The workflow for the outsourcing in the <code>secrets.yaml</code> are very similar to the <a href="/topics/splitting_configuration/">splitting of the configuration</a>. Create a <code>secrets.yaml</code> file in your Home assistant configuration directory (The location of the folder differs between operating systems: on OS X and Linux it’s <code>~/.homeassistant</code> and on Windows it’s <code>%APPDATA%/.homeassistant</code>).</p>
<p>The entries for password and API keys in the <code>configuration.yaml</code> file usally looks like the example below.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre><span class="key">http</span>:
<span class="key">api_password</span>: <span class="string"><span class="content">YOUR_PASSWORD</span></span>
</pre></div>
</div>
</div>
<p>Those entries need to be replaced with <code>!secret</code> and a identifier.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre><span class="key">http</span>:
<span class="key">api_password</span>: <span class="type">!secret</span> <span class="string"><span class="content">http_password</span></span>
</pre></div>
</div>
</div>
<p>The <code>secrets.yaml</code> files stored the corresponding password assigned to the identifier.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre><span class="key">logger</span>: <span class="string"><span class="content">debug</span></span>
<span class="key">http_password</span>: <span class="string"><span class="content">YOUR_PASSWORD</span></span>
</pre></div>
</div>
</div>
<h3><a class="title-link" name="python-keyring" href="#python-keyring"></a> Python Keyring</h3>
<p>Using <a href="http://pythonhosted.org/keyring/">Keyring</a> is an alternative way to <code>secrets.yaml</code> but requires that <code>keyring</code> is installed (incl. its command-line tools). This can be done with:</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>$ pip3 install keyring
</pre></div>
</div>
</div>
<p>Replaced your password or API key with <code>!secret</code> and an identifier in <code>configuration.yaml</code> file.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre><span class="key">http</span>:
<span class="key">api_password</span>: <span class="type">!secret</span> <span class="string"><span class="content">http_password</span></span>
</pre></div>
</div>
</div>
<p>Create an entry in your keyring. The service (SERVICE) is <code>homeassistant</code> and the identifier is the USERNAME in the keyring context.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>$ keyring set homeassistant http_password
Password for 'http_password' in 'homeassistant':
Please set a password for your new keyring:
Please confirm the password:
</pre></div>
</div>
</div>
<p>If the command-line tool <code>keyring</code> is not available, launch <code>python3</code> and do the process manually.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>&gt;&gt;&gt; <span class="keyword">import</span> <span class="include">keyring</span>
&gt;&gt;&gt; keyring.set_password(<span class="string"><span class="delimiter">&quot;</span><span class="content">homeassistant</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">http_password</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">12345</span><span class="delimiter">&quot;</span></span>)
Please <span class="predefined">set</span> a password <span class="keyword">for</span> your new keyring:
Please confirm the password:
&gt;&gt;&gt; keyring.get_password(<span class="string"><span class="delimiter">&quot;</span><span class="content">homeassistant</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">http_password</span><span class="delimiter">&quot;</span></span>)
<span class="string"><span class="delimiter">'</span><span class="content">12345</span><span class="delimiter">'</span></span>
&gt;&gt;&gt; keyring.get_keyring()
&lt;EncryptedKeyring at /home/your_user/.local/share/python_keyring/crypted_pass.cfg&gt;
</pre></div>
</div>
</div>
<p>If you launch home Assistant now, you will be prompted for the keyring password to unlock your keyring.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>$ hass
Config directory: /home/fab/.homeassistant
Please enter password for encrypted keyring:
</pre></div>
</div>
</div>
<p class="note warning">
If your are using the Python Keyring, <a href="/getting-started/autostart/">autostarting</a> of Home Assistant will no longer work.
</p>
</article>
</div>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item">
<div class="copyright">
<a rel="me" href='https://twitter.com/home_assistant'><i class="icon-twitter"></i></a>
<a rel="me" href='https://github.com/home-assistant/home-assistant'><i class="icon-github"></i></a>
<div class="credit">
Contact us at <a href='mailto:hello@home-assistant.io'>hello@home-assistant.io</a>.<br>
Website powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>.<br />
Hosted by <a href='https://pages.github.com/'>GitHub</a> and served by <a href='https://cloudflare.com'>CloudFlare</a>.
</div>
</div>
</div>
</div>
</div>
</footer>
<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>

324
topics/splitting_configuration/index.html
View file

@ -1,324 +0,0 @@
<!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>Splitting up the configuration - Home Assistant</title>
<meta name="author" content="Home Assistant">
<meta name="description" content="Splitting the configuration.yaml into several files.">
<meta name="viewport" content="width=device-width">
<link rel="canonical" href="https://home-assistant.io/topics/splitting_configuration/">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="Splitting up the configuration">
<meta property="og:site_name" content="Home Assistant">
<meta property="og:url" content="https://home-assistant.io/topics/splitting_configuration/">
<meta property="og:type" content="article">
<meta property="og:description" content="Splitting the configuration.yaml into several files.">
<meta property="og:image" content="https://home-assistant.io/images/default-social.png">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@home_assistant">
<meta name="twitter:title" content="Splitting up the configuration">
<meta name="twitter:description" content="Splitting the configuration.yaml into several files.">
<meta name="twitter:image" content="https://home-assistant.io/images/default-social.png">
<link href="/stylesheets/screen.css" media="screen, projection" rel="stylesheet">
<link href="/atom.xml" rel="alternate" title="Home Assistant" type="application/atom+xml">
<link rel='shortcut icon' href='/images/favicon.ico' />
<link rel='icon' type='image/png' href='/images/favicon-192x192.png' sizes='192x192' />
</head>
<body >
<header>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item three-tenths lap-two-sixths palm-one-whole ha-title">
<a href="/" class="site-title">
<img width='40' src='/demo/favicon-192x192.png'>
<span>Home Assistant</span>
</a>
</div>
<div class="grid__item seven-tenths lap-four-sixths palm-one-whole">
<nav>
<input type="checkbox" id="toggle">
<label for="toggle" class="toggle" data-open="Main Menu" data-close="Close Menu"></label>
<ul class="menu pull-right">
<li><a href='/getting-started/'>Getting started</a></li>
<li><a href='/components/'>Components</a></li>
<li><a href='/cookbook/'>Examples</a></li>
<li><a href="/developers/">Developers</a></li>
<li><a href="/blog/">Blog</a></li>
<li><a href="/help/">Need help?</a></li>
</ul>
</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">
<div class='edit-github'><a href='https://github.com/home-assistant/home-assistant.io/tree/master/source/_topics/splitting_configuration.markdown'>Edit this page on GitHub</a></div>
<header>
<h1 class="title indent">
Splitting Up the Configuration
</h1>
</header>
<hr class="divider">
<p>So you’ve been using Home Assistant for a while now and your <a href="https://home-assistant.io/cookbook/configuration_yaml_from_bassclarinetl2/">configuration.yaml file brings people to tears</a> or you simply want to start off with the distributed approach, here’s how to “split the configuration.yaml” into more manageable (read: humanly readable) pieces.</p>
<p>First off, several community members have sanitized (read: without api keys/passwords etc) versions of their configurations available for viewing, you can see a list of them <a href="https://home-assistant.io/cookbook/#example-configurationyaml">here</a>.</p>
<p>As commenting code doesn’t always happen, please read on for the details.</p>
<p>Now despite the logical assumption that the <code>configuration.yaml</code> will be replaced by this process it will in fact remain all be it in a much less cluttered form.</p>
<p>In this lighter version we will still need what could be called the core snippet:</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre><span class="key">homeassistant</span>:
<span class="comment"># Name of the location where Home Assistant is running</span>
<span class="key">name</span>: <span class="string"><span class="content">My Home Assistant Instance</span></span>
<span class="comment"># Location required to calculate the time the sun rises and sets</span>
<span class="key">latitude</span>: <span class="string"><span class="content">37</span></span>
<span class="key">longitude</span>: <span class="string"><span class="content">-121</span></span>
<span class="comment"># C for Celsius, F for Fahrenheit</span>
<span class="key">temperature_unit</span>: <span class="string"><span class="content">F</span></span>
<span class="comment"># Pick yours from here: http://en.wikipedia.org/wiki/List_of_tz_database_time_zones</span>
<span class="key">time_zone</span>: <span class="string"><span class="content">America/Los_Angeles</span></span>
<span class="key">customize</span>: <span class="type">!include</span> <span class="string"><span class="content">customize.yaml</span></span>
</pre></div>
</div>
</div>
<p>Note that each line after <code>homeassistant:</code> is indented two (2) spaces. Since the configuration files in Home Assistant are based on the YAML language, indentation and spacing are important. Also note that seemingly strange entry under <code>customize:</code>.</p>
<p><code>!include filename.yaml</code> is the statement that tells Home Assistant to insert the contents of <code>filename.yaml</code> at that point. This is how we are going to break a monolithic and hard to read file (when it gets big) into more manageable chunks.</p>
<p>Now before we start splitting out the different components, let’s look at the other components (in our example) that will stay in the base file:</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre><span class="key">history</span>:
<span class="key">frontend</span>:
<span class="key">logbook</span>:
<span class="key">http</span>:
<span class="key">api_password</span>: <span class="string"><span class="content">ImNotTelling!</span></span>
<span class="key">ifttt</span>:
<span class="key">key</span>: <span class="string"><span class="content">[nope]</span></span>
<span class="key">wink</span>:
<span class="key">access_token</span>: <span class="string"><span class="content">[wouldn't you]</span></span>
<span class="key">refresh_token</span>: <span class="string"><span class="content">[like to know]</span></span>
<span class="key">zwave</span>:
<span class="key">usb_path</span>: <span class="string"><span class="content">/dev/ttyUSB0</span></span>
<span class="key">config_path</span>: <span class="string"><span class="content">/usr/local/share/python-openzwave/config</span></span>
<span class="key">polling_interval</span>: <span class="string"><span class="content">10000</span></span>
<span class="comment">#zigbee:</span>
<span class="comment"># device: /dev/ttyUSB1</span>
<span class="comment"># baud: 115200</span>
<span class="key">mqtt</span>:
<span class="key">broker</span>: <span class="string"><span class="content">127.0.0.1</span></span>
</pre></div>
</div>
</div>
<p>As with the core snippet, indentation makes a difference. The component headers (<code>mqtt:</code>) should be fully left aligned (aka no indent), and the parameters (<code>port:</code>) should be indented two (2) spaces.</p>
<p>While some of these components can technically be moved to a separate file they are so small or “one off’s” where splitting them off is superfluous. Also, you’ll notice the # symbol (hash/pound). This represents a “comment” as far as the commands are interpreted. Put another way, any line prefixed with a <code>#</code> will be ignored. This makes breaking up files for human readability really convenient, not to mention turning off features while leaving the entry intact. (Look at the <code>zigbee:</code> entry above and the b entry further down)</p>
<p>Now, lets assume that a blank file has been created in the Home Assistant configuration directory for each of the following:</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>automation.yaml
zones.yaml
sensors.yaml
switches.yaml
device_tracker.yaml
customize.yaml
</pre></div>
</div>
</div>
<p><code>automation.yaml</code> will hold all the automation component details. <code>zones.yaml</code> will hold the zone component details and so forth. These files can be called anything but giving them names that match their function will make things easier to keep track of.</p>
<p>Inside the base configuration file add the following entries:</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre><span class="key">automation</span>: <span class="type">!include</span> <span class="string"><span class="content">automation.yaml</span></span>
<span class="key">zone</span>: <span class="type">!include</span> <span class="string"><span class="content">zones.yaml</span></span>
<span class="key">sensor</span>: <span class="type">!include</span> <span class="string"><span class="content">sensors.yaml</span></span>
<span class="key">switch</span>: <span class="type">!include</span> <span class="string"><span class="content">switches.yaml</span></span>
<span class="key">device_tracker</span>: <span class="type">!include</span> <span class="string"><span class="content">device_tracker.yaml</span></span>
</pre></div>
</div>
</div>
<p>Note that there can only be one <code>!include:</code> for each component so chaining them isn’t going to work. If that sounds like greek, don’t worry about it.</p>
<p>Alright, so we’ve got the single components and the include statements in the base file, what goes in those extra files?</p>
<p>Let’s look at the <code>device_tracker.yaml</code> file from our example:</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>- <span class="string"><span class="content">platform: owntracks</span></span>
- <span class="string"><span class="content">platform: nmap_tracker</span></span>
<span class="key">hosts</span>: <span class="string"><span class="content">192.168.2.0/24</span></span>
<span class="key">home_interval</span>: <span class="string"><span class="content">3</span></span>
<span class="key">track_new_devices</span>: <span class="string"><span class="content">yes</span></span>
<span class="key">interval_seconds</span>: <span class="string"><span class="content">40</span></span>
<span class="key">consider_home</span>: <span class="string"><span class="content">120</span></span>
</pre></div>
</div>
</div>
<p>This small example illustrates how the “split” files work. In this case, we start with a “comment block” identifying the file followed by two (2) device tracker entries (<code>owntracks</code> and <code>nmap</code>). These files follow <a href="/getting-started/devices/#style-2-list-each-device-separately">“style 1”</a> that is to say a fully left aligned leading entry (<code>- platform: owntracks</code>) followed by the parameter entries indented two (2) spaces.</p>
<p>This (large) sensor configuration gives us another example:</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre><span class="comment">### sensors.yaml</span>
<span class="comment">##############################################################</span>
<span class="comment">### METEOBRIDGE ####</span>
<span class="comment">##############################################################</span>
- <span class="string"><span class="content">platform: tcp</span></span>
<span class="key">name</span>: <span class="string"><span class="content">'Outdoor Temp (Meteobridge)'</span></span>
<span class="key">host</span>: <span class="string"><span class="content">192.168.2.82</span></span>
<span class="key">timeout</span>: <span class="string"><span class="content">6</span></span>
<span class="key">payload</span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">Content-type: text/xml; charset=UTF-8\n\n</span><span class="delimiter">&quot;</span></span>
<span class="key">value_template</span>: <span class="string"><span class="delimiter">&quot;</span><span class="delimiter">&quot;</span></span>
<span class="key">unit</span>: <span class="string"><span class="content">C</span></span>
- <span class="string"><span class="content">platform: tcp</span></span>
<span class="key">name</span>: <span class="string"><span class="content">'Outdoor Humidity (Meteobridge)'</span></span>
<span class="key">host</span>: <span class="string"><span class="content">192.168.2.82</span></span>
<span class="key">port</span>: <span class="string"><span class="content">5556</span></span>
<span class="key">timeout</span>: <span class="string"><span class="content">6</span></span>
<span class="key">payload</span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">Content-type: text/xml; charset=UTF-8\n\n</span><span class="delimiter">&quot;</span></span>
<span class="key">value_template</span>: <span class="string"><span class="delimiter">&quot;</span><span class="delimiter">&quot;</span></span>
<span class="key">unit</span>: <span class="string"><span class="content">Percent</span></span>
- <span class="string"><span class="content">platform: tcp</span></span>
<span class="key">name</span>: <span class="string"><span class="content">'Outdoor Dewpoint (Meteobridge)'</span></span>
<span class="key">host</span>: <span class="string"><span class="content">192.168.2.82</span></span>
<span class="key">port</span>: <span class="string"><span class="content">5556</span></span>
<span class="key">timeout</span>: <span class="string"><span class="content">6</span></span>
<span class="key">payload</span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">Content-type: text/xml; charset=UTF-8\n\n</span><span class="delimiter">&quot;</span></span>
<span class="key">value_template</span>: <span class="string"><span class="delimiter">&quot;</span><span class="delimiter">&quot;</span></span>
<span class="key">unit</span>: <span class="string"><span class="content">C</span></span>
<span class="comment">###################################</span>
<span class="comment">#### STEAM FRIENDS ####</span>
<span class="comment">##################################</span>
- <span class="string"><span class="content">platform: steam_online</span></span>
<span class="key">api_key</span>: <span class="string"><span class="content">[not telling]</span></span>
<span class="key">accounts</span>:
- <span class="string"><span class="content">76561198012067051</span></span>
<span class="comment">##################################</span>
<span class="comment">#### TIME/DATE ####</span>
<span class="comment">##################################</span>
- <span class="string"><span class="content">platform: time_date</span></span>
<span class="key">display_options</span>:
- <span class="string"><span class="content">'time'</span></span>
- <span class="string"><span class="content">'date'</span></span>
- <span class="string"><span class="content">platform: worldclock</span></span>
<span class="key">time_zone</span>: <span class="string"><span class="content">Etc/UTC</span></span>
<span class="key">name</span>: <span class="string"><span class="content">'UTC'</span></span>
- <span class="string"><span class="content">platform: worldclock</span></span>
<span class="key">time_zone</span>: <span class="string"><span class="content">America/New_York</span></span>
<span class="key">name</span>: <span class="string"><span class="content">'Ann Arbor'</span></span>
- <span class="string"><span class="content">platform: worldclock</span></span>
<span class="key">time_zone</span>: <span class="string"><span class="content">Europe/Vienna</span></span>
<span class="key">name</span>: <span class="string"><span class="content">'Innsbruck'</span></span>
- <span class="string"><span class="content">platform: worldclock</span></span>
<span class="key">time_zone</span>: <span class="string"><span class="content">America/New_York</span></span>
<span class="key">name</span>: <span class="string"><span class="content">'Ann Arbor'</span></span>
</pre></div>
</div>
</div>
<p>You’ll notice that this example includes a secondary parameter section (under the steam section) as well as a better example of the way comments can be used to break down files into sections.</p>
<p>That about wraps it up.</p>
<p>If you have issues checkout <code>home-assistant.log</code> in the configuration directory as well as your indentations. If all else fails, head over to the <a href="https://gitter.im/balloob/home-assistant">Gitter Chatroom</a> and ask away.</p>
<h3><a class="title-link" name="advanced-usage" href="#advanced-usage"></a> Advanced usage</h3>
<p>We offer four advanced options to include whole directories at once.</p>
<p><code>!include_dir_list</code> will return content of a directory as a list with each file content being an entry in the list.</p>
<p><code>!include_dir_named</code> will return content of a directory as a dictionary which maps filename =&gt; content of file.</p>
<p><code>!include_dir_merge_list</code> will return content of a directory as a list by merging all files (which should contain a list) into 1 big list.</p>
<p><code>!include_dir_merge_named</code> will return content of a directory as a dictionary by loading each file and merging it into 1 big dictionary.</p>
</article>
</div>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item">
<div class="copyright">
<a rel="me" href='https://twitter.com/home_assistant'><i class="icon-twitter"></i></a>
<a rel="me" href='https://github.com/home-assistant/home-assistant'><i class="icon-github"></i></a>
<div class="credit">
Contact us at <a href='mailto:hello@home-assistant.io'>hello@home-assistant.io</a>.<br>
Website powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>.<br />
Hosted by <a href='https://pages.github.com/'>GitHub</a> and served by <a href='https://cloudflare.com'>CloudFlare</a>.
</div>
</div>
</div>
</div>
</div>
</footer>
<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>

214
topics/state_object/index.html
View file

@ -1,214 +0,0 @@
<!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>State Objects - Home Assistant</title>
<meta name="author" content="Home Assistant">
<meta name="description" content="Describes all there is to know about state objects in Home Assistant.">
<meta name="viewport" content="width=device-width">
<link rel="canonical" href="https://home-assistant.io/topics/state_object/">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="State Objects">
<meta property="og:site_name" content="Home Assistant">
<meta property="og:url" content="https://home-assistant.io/topics/state_object/">
<meta property="og:type" content="article">
<meta property="og:description" content="Describes all there is to know about state objects in Home Assistant.">
<meta property="og:image" content="https://home-assistant.io/images/default-social.png">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@home_assistant">
<meta name="twitter:title" content="State Objects">
<meta name="twitter:description" content="Describes all there is to know about state objects in Home Assistant.">
<meta name="twitter:image" content="https://home-assistant.io/images/default-social.png">
<link href="/stylesheets/screen.css" media="screen, projection" rel="stylesheet">
<link href="/atom.xml" rel="alternate" title="Home Assistant" type="application/atom+xml">
<link rel='shortcut icon' href='/images/favicon.ico' />
<link rel='icon' type='image/png' href='/images/favicon-192x192.png' sizes='192x192' />
</head>
<body >
<header>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item three-tenths lap-two-sixths palm-one-whole ha-title">
<a href="/" class="site-title">
<img width='40' src='/demo/favicon-192x192.png'>
<span>Home Assistant</span>
</a>
</div>
<div class="grid__item seven-tenths lap-four-sixths palm-one-whole">
<nav>
<input type="checkbox" id="toggle">
<label for="toggle" class="toggle" data-open="Main Menu" data-close="Close Menu"></label>
<ul class="menu pull-right">
<li><a href='/getting-started/'>Getting started</a></li>
<li><a href='/components/'>Components</a></li>
<li><a href='/cookbook/'>Examples</a></li>
<li><a href="/developers/">Developers</a></li>
<li><a href="/blog/">Blog</a></li>
<li><a href="/help/">Need help?</a></li>
</ul>
</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">
<div class='edit-github'><a href='https://github.com/home-assistant/home-assistant.io/tree/master/source/_topics/state_object.markdown'>Edit this page on GitHub</a></div>
<header>
<h1 class="title indent">
State Objects
</h1>
</header>
<hr class="divider">
<p>Your devices are represented in Home Assistant as entities. The entities will write their current state to the state machine for other entities/templates/frontend to access. States are a current representation of the entity.</p>
<p>If you overwrite a state via the states dev tool or the API, it will not impact the actual device. If the device state is being polled, it will overwrite the state in the state machine the next polling.</p>
<p>All states will always have an entity id, a state and a timestamp when last updated and last changed.</p>
<table>
<thead>
<tr>
<th>Field</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>state.entity_id</code></td>
<td>Entity ID. Format: <code>&lt;domain&gt;.&lt;object_id&gt;</code>. Example: <code>light.kitchen</code>.</td>
</tr>
<tr>
<td><code>state.domain</code></td>
<td>Domain of the entity. Example: <code>light</code>.</td>
</tr>
<tr>
<td><code>state.object_id</code></td>
<td>Object ID of entity. Example: <code>kitchen</code>.</td>
</tr>
<tr>
<td><code>state.name</code></td>
<td>Name of the entity. Based on <code>friendly_name</code> attribute with fall back to object ID. Example: <code>Kitchen Ceiling</code>.</td>
</tr>
<tr>
<td><code>state.last_updated</code></td>
<td>Time the state was written to the state machine. Note that writing the exact same state including attributes will not result in this field being updated. Example: <code>14:10:03 13-03-2016</code>.</td>
</tr>
<tr>
<td><code>state.last_changed</code></td>
<td>Time the state changed. This is not updated when there are only updated attributes. Example: <code>14:10:03 13-03-2016</code>.</td>
</tr>
<tr>
<td><code>state.attributes</code></td>
<td>A dictionary with extra attributes related to the current state.</td>
</tr>
</tbody>
</table>
<p>The attributes of an entity are optional. There are a few attributes that are used by Home Assistant for representing the entity in a specific way. Each component will also have it’s own attributes to represent extra state data about the entity. For example, the light component has attributes for the current brightness and color of the light. When an attribute is not available, Home Assistant will not write it to the state.</p>
<p>When using templates, attributes will be available by their name. For example <code>state.attributes.assumed_state</code>.</p>
<table>
<thead>
<tr>
<th>Attribute</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>friendly_name</code></td>
<td>Name of the entity. Example: <code>Kitchen Ceiling</code>.</td>
</tr>
<tr>
<td><code>icon</code></td>
<td>Icon to use for the entity in the frontend. Example: <code>mdi:home</code>.</td>
</tr>
<tr>
<td><code>hidden</code></td>
<td>Boolean if the entity should not be shown in the frontend. Example: <code>true</code>.</td>
</tr>
<tr>
<td><code>entity_picture</code></td>
<td>Url to a picture that should be used instead of showing the domain icon. Example: <code>http://example.com/picture.jpg</code>.</td>
</tr>
<tr>
<td><code>assumed_state</code></td>
<td>Boolean if the current state is an assumption. <a href="https://home-assistant.io/blog/2016/02/12/classifying-the-internet-of-things/#classifiers">More info</a> Example: <code>True</code>.</td>
</tr>
<tr>
<td><code>unit_of_measurement</code></td>
<td>The unit of measurement the state is expressed in. Used for grouping graphs or understanding the entity. Example: <code>°C</code>.</td>
</tr>
</tbody>
</table>
</article>
</div>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item">
<div class="copyright">
<a rel="me" href='https://twitter.com/home_assistant'><i class="icon-twitter"></i></a>
<a rel="me" href='https://github.com/home-assistant/home-assistant'><i class="icon-github"></i></a>
<div class="credit">
Contact us at <a href='mailto:hello@home-assistant.io'>hello@home-assistant.io</a>.<br>
Website powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>.<br />
Hosted by <a href='https://pages.github.com/'>GitHub</a> and served by <a href='https://cloudflare.com'>CloudFlare</a>.
</div>
</div>
</div>
</div>
</div>
</footer>
<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>

344
topics/templating/index.html
View file

@ -1,344 +0,0 @@
<!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>Templating - Home Assistant</title>
<meta name="author" content="Home Assistant">
<meta name="description" content="Instructions how to use the templating feature of Home Assistant.">
<meta name="viewport" content="width=device-width">
<link rel="canonical" href="https://home-assistant.io/topics/templating/">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="Templating">
<meta property="og:site_name" content="Home Assistant">
<meta property="og:url" content="https://home-assistant.io/topics/templating/">
<meta property="og:type" content="article">
<meta property="og:description" content="Instructions how to use the templating feature of Home Assistant.">
<meta property="og:image" content="https://home-assistant.io/images/default-social.png">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@home_assistant">
<meta name="twitter:title" content="Templating">
<meta name="twitter:description" content="Instructions how to use the templating feature of Home Assistant.">
<meta name="twitter:image" content="https://home-assistant.io/images/default-social.png">
<link href="/stylesheets/screen.css" media="screen, projection" rel="stylesheet">
<link href="/atom.xml" rel="alternate" title="Home Assistant" type="application/atom+xml">
<link rel='shortcut icon' href='/images/favicon.ico' />
<link rel='icon' type='image/png' href='/images/favicon-192x192.png' sizes='192x192' />
</head>
<body >
<header>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item three-tenths lap-two-sixths palm-one-whole ha-title">
<a href="/" class="site-title">
<img width='40' src='/demo/favicon-192x192.png'>
<span>Home Assistant</span>
</a>
</div>
<div class="grid__item seven-tenths lap-four-sixths palm-one-whole">
<nav>
<input type="checkbox" id="toggle">
<label for="toggle" class="toggle" data-open="Main Menu" data-close="Close Menu"></label>
<ul class="menu pull-right">
<li><a href='/getting-started/'>Getting started</a></li>
<li><a href='/components/'>Components</a></li>
<li><a href='/cookbook/'>Examples</a></li>
<li><a href="/developers/">Developers</a></li>
<li><a href="/blog/">Blog</a></li>
<li><a href="/help/">Need help?</a></li>
</ul>
</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">
<div class='edit-github'><a href='https://github.com/home-assistant/home-assistant.io/tree/master/source/_topics/templating.markdown'>Edit this page on GitHub</a></div>
<header>
<h1 class="title indent">
Templating
</h1>
</header>
<hr class="divider">
<p>This is an advanced feature of Home Assistant. You’ll need a basic understanding of the following things:</p>
<ul>
<li><a href="/developers/architecture/">Home Assistant architecture</a>, especially states.</li>
<li><a href="/topics/state_object/">State object</a></li>
</ul>
<p>Templating is a powerful feature in Home Assistant that allows the user control over information that is going into and out of the system. It is used for:</p>
<ul>
<li>Formatting outgoing messages in, for example, the <a href="/components/notify/">notify</a> and <a href="/components/alexa/">alexa</a> components.</li>
<li>Process incoming data from sources that provide raw data, like <a href="/components/mqtt/">MQTT</a>, <a href="/components/sensor.rest/">Rest sensor</a> or the <a href="/components/sensor.command_line/">command line sensor</a>.</li>
</ul>
<h2><a class="title-link" name="building-templates" href="#building-templates"></a> Building templates</h2>
<p>Templating in Home Assistant is powered by the Jinja2 templating engine. This means that we are using their syntax and make some custom Home Assistant variables available to templates during rendering. We will not go over the basics of the syntax, as Jinja2 does a lot better job at this in their <a href="http://jinja.pocoo.org/docs/dev/templates/">Jinja2 documentation</a>.</p>
<p class="note">
The frontend has a template editor developer tool to help develop and debug templates.
</p>
<p>Templates can get big pretty fast. To keep a clear overview, consider using YAML multiline strings to define your templates:</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre><span class="key">script</span>:
<span class="key">msg_who_is_home</span>:
<span class="key">sequence</span>:
- <span class="string"><span class="content">service: notify.notify</span></span>
<span class="key">data</span>:
<span class="key">message</span>: <span class="string"><span class="delimiter">&gt;</span><span class="content">
{% if is_state('device_tracker.paulus', 'home') %}
Ha, Paulus is home!
{% else %}
Paulus is at {{ states('device_tracker.paulus')) }}.
{% endif %}</span></span>
</pre></div>
</div>
</div>
<h2><a class="title-link" name="home-assistant-template-extensions" href="#home-assistant-template-extensions"></a> Home Assistant template extensions</h2>
<p>Home Assistant adds extensions to allow templates to access all of the current states:</p>
<ul>
<li>Iterating <code>states</code> will yield each state sorted alphabetically by entity ID.</li>
<li>Iterating <code>states.domain</code> will yield each state of that domain sorted alphabetically by entity ID.</li>
<li><code>states.sensor.temperature</code> returns the state object for <code>sensor.temperature</code>.</li>
<li><code>states('device_tracker.paulus')</code> will return the state string (not the object) of the given entity or <code>unknown</code> if it doesn’t exist.</li>
<li><code>is_state('device_tracker.paulus', 'home')</code> will test if the given entity is specified state.</li>
<li><code>is_state_attr('device_tracker.paulus', 'battery', 40)</code> will test if the given entity is specified state.</li>
<li>Filter <code>multiply(x)</code> will convert the input to a number and multiply it with <code>x</code>.</li>
<li>Filter <code>round(x)</code> will convert the input to a number and round it to <code>x</code> decimals.</li>
<li><code>now</code> will be rendered as current time in your time zone.</li>
<li><code>utcnow</code> will be rendered as UTC time.</li>
<li><code>as_timestamp</code> will convert datetime object or string to UNIX timestamp</li>
<li><code>distance()</code> will measure the distance in meters between home, entity, coordinates.</li>
<li><code>closest()</code> will find the closest entity.</li>
<li><code>relative_time(timestamp)</code> will format the date time as relative time vs now (ie 7 seconds)</li>
<li><code>float</code> will format the output as float.</li>
</ul>
<h2><a class="title-link" name="examples" href="#examples"></a> Examples</h2>
<h3><a class="title-link" name="states" href="#states"></a> States</h3>
<p>Next two statements result in same value if state exists. Second one will result in an error if state does not exist.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>
{{ states('device_tracker.paulus') }}
{{ states.device_tracker.paulus.state }}
</pre></div>
</div>
</div>
<h3><a class="title-link" name="attributes" href="#attributes"></a> Attributes</h3>
<p>Print an attribute if state is defined</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>
{% if states.device_tracker.paulus %}
{{ states.device_tracker.paulus.attributes.battery }}
{% else %}
??
{% endif %}
</pre></div>
</div>
</div>
<h3><a class="title-link" name="sensor-states" href="#sensor-states"></a> Sensor states</h3>
<p>Print out a list of all the sensor states.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>
{% for state in states.sensor %}
{{ state.entity_id }}={{ state.state }},
{% endfor %}
{% if is_state('device_tracker.paulus', 'home') %}
Ha, Paulus is home!
{% else %}
Paulus is at {{ states('device_tracker.paulus')) }}.
{% endif %}
{{ states.sensor.temperature | multiply(10) | round(2) }}
{% if states('sensor.temperature') | float &gt; 20 %}
It is warm!
{%endif %}
{{ as_timestamp(states.binary_sensor.garage_door.last_changed) }}
{{ as_timestamp(now) - as_timestamp(states.binary_sensor.garage_door.last_changed) }}
</pre></div>
</div>
</div>
<h3><a class="title-link" name="distance-examples" href="#distance-examples"></a> Distance examples</h3>
<p>If only 1 location is passed in will measure the distance from home.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>
Using Lat Lng coordinates: {{ distance(123.45, 123.45) }}
Using State: {{ distance(device_tracker.paulus) }}
These can also be combined in any combination:
{{ distance(123.45, 123.45, device_tracker.paulus) }}
{{ distance(device_tracker.anne_therese, device_tracker.paulus) }}
</pre></div>
</div>
</div>
<h3><a class="title-link" name="closest-examples" href="#closest-examples"></a> Closest examples</h3>
<p>Find entities closest to the Home Assistant location:</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>
Query all entities: {{ closest(states) }}
Query all entities of a specific domain: {{ closest(states.device_tracker) }}
Query all entities in group.children: {{ closest('group.children') }}
Query all entities in group.children: {{ closest(states.group.children) }}
</pre></div>
</div>
</div>
<p>Find entities closest to a coordinate or another entity. All previous arguments still apply for 2nd argument.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>
Closest to a coordinate: {{ closest(23.456, 23.456, 'group.children') }}
Closest to an entity: {{ closest('zone.school', 'group.children') }}
Closest to an entity: {{ closest(states.zone.school, 'group.children') }}
</pre></div>
</div>
</div>
<h3><a class="title-link" name="combined" href="#combined"></a> Combined</h3>
<p>Since closest returns a state, we can combine it with distance too</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>
{{ closest(states).name }} is {{ distance(closest(states)) }} meters away.
</pre></div>
</div>
</div>
<h2><a class="title-link" name="processing-incoming-data" href="#processing-incoming-data"></a> Processing incoming data</h2>
<p>The other part of templating is processing incoming data. It will allow you to modify incoming data and extract only the data you care about. This will work only for platforms and components that mentioned support for this in their documentation.</p>
<p>It depends per component or platform but it is common to be able to define a template using the <code>value_template</code> configuration key. When a new value arrives, your template will be rendered while having access to the following values on top of the usual Home Assistant extensions:</p>
<table>
<thead>
<tr>
<th>Variable</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>value</code></td>
<td>The incoming value.</td>
</tr>
<tr>
<td><code>value_json</code></td>
<td>The incoming value parsed as JSON.</td>
</tr>
</tbody>
</table>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre># Incoming value:
{&quot;primes&quot;: [2, 3, 5, 7, 11, 13]}
# Extract third prime number
{{ value_json.primes[2] }}
# Format output
{{ &quot;%+.1f&quot; | value_json }}
# Calculations
{{ value_json | multiply(1024) }}
{{ value_json.used | multiply(0.0001) | round(0) }}
</pre></div>
</div>
</div>
</article>
</div>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item">
<div class="copyright">
<a rel="me" href='https://twitter.com/home_assistant'><i class="icon-twitter"></i></a>
<a rel="me" href='https://github.com/home-assistant/home-assistant'><i class="icon-github"></i></a>
<div class="credit">
Contact us at <a href='mailto:hello@home-assistant.io'>hello@home-assistant.io</a>.<br>
Website powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>.<br />
Hosted by <a href='https://pages.github.com/'>GitHub</a> and served by <a href='https://cloudflare.com'>CloudFlare</a>.
</div>
</div>
</div>
</div>
</div>
</footer>
<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>