jeena/home-assistant.github.io
1
0
Fork 0
Code Issues Pull requests Projects Packages Wiki Activity Actions
home-assistant.github.io/docs/configuration/yaml/index.html
Travis CI 7344d8208c Site updated at 2018-01-31 09:37:28 UTC
2018-01-31 09:37:28 +00:00

402 lines
23 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!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>YAML - Home Assistant</title>
<meta name="author" content="Home Assistant">
<meta name="description" content="Details about YAML to configure Home Assistant.">
<meta name="viewport" content="width=device-width">
<link rel="canonical" href="https://home-assistant.io/docs/configuration/yaml/">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="YAML">
<meta property="og:site_name" content="Home Assistant">
<meta property="og:url" content="https://home-assistant.io/docs/configuration/yaml/">
<meta property="og:type" content="article">
<meta property="og:description" content="Details about YAML to configure 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="YAML">
<meta name="twitter:description" content="Details about YAML to configure Home Assistant.">
<meta name="twitter:image" content="https://home-assistant.io/images/default-social.png">
<link href="/stylesheets/screen.css" media="screen, projection, print" 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 class='site-header'>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item three-tenths lap-two-sixths palm-one-whole ha-title">
<a href="/" class="site-title">
<img width='40' src='/demo/favicon-192x192.png'>
<span>Home Assistant</span>
</a>
</div>
<div class="grid__item seven-tenths lap-four-sixths palm-one-whole">
<nav>
<input type="checkbox" id="toggle">
<label for="toggle" class="toggle" data-open="Main Menu" data-close="Close Menu"></label>
<ul class="menu pull-right">
<li><a href="/getting-started/">Getting started</a></li>
<li><a href="/components/">Components</a></li>
<li><a href="/docs/">Docs</a></li>
<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>
<li><a href='#' class='show-search'><i class="icon-search"></i></a></li>
</ul>
</nav>
<div class='search-container' style='display: none'>
<div class='search'>
<i class="icon-search"></i>
<input id='search' placeholder='Search the docs…'>
<a href='#' class='close'><i class="icon-remove-sign"></i></a>
</div>
</div>
</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.github.io/tree/current/source/_docs/configuration/yaml.markdown'>Edit this page on GitHub</a></div>
<header>
<h1 class="title indent">
YAML
</h1>
</header>
<hr class="divider">
<p>Home Assistant uses the <a href="http://yaml.org/">YAML</a> syntax for configuration. YAML might take a while to get used to but is really powerful in allowing you to express complex configurations.</p>
<p>For each component that you want to use in Home Assistant, you add code in your <code class="highlighter-rouge">configuration.yaml</code> file to specify its settings.
The following example entry specifies that you want to use the <a href="/components/notify">notify component</a> with the <a href="/components/notify.pushbullet">pushbullet platform</a>.</p>
<div class="language-yaml highlighter-rouge"><pre class="highlight"><code><span class="s">notify</span><span class="pi">:</span>
<span class="s">platform</span><span class="pi">:</span> <span class="s">pushbullet</span>
<span class="s">api_key</span><span class="pi">:</span> <span class="s2">"</span><span class="s">o.1234abcd"</span>
<span class="s">name</span><span class="pi">:</span> <span class="s">pushbullet</span>
</code></pre>
</div>
<ul>
<li>A <strong>component</strong> provides the core logic for some functionality (like <code class="highlighter-rouge">notify</code> provides sending notifications).</li>
<li>A <strong>platform</strong> makes the connection to a specific software or hardware platform (like <code class="highlighter-rouge">pushbullet</code> works with the service from pushbullet.com).</li>
</ul>
<p>The basics of YAML syntax are block collections and mappings containing key-value pairs. Each item in a collection starts with a <code class="highlighter-rouge">-</code> while mappings have the format <code class="highlighter-rouge">key: value</code>. If you specify duplicate keys, the last value for a key is used. This is somewhat similar to a Hashtable or more specifically a dictionary in Python. These can be nested as well.</p>
<p>Note that indentation is an important part of specifying relationships using YAML. Things that are indented are nested “inside” things that are one level higher. So in the above example, <code class="highlighter-rouge">platform: pushbullet</code> is a property of (nested inside) the <code class="highlighter-rouge">notify</code> component.</p>
<p>Getting the right indentation can be tricky if you’re not using an editor with a fixed width font. Tabs are not allowed to be used for indentation. Convention is to use 2 spaces for each level of indentation.</p>
<p>You can use the online service <a href="http://www.yamllint.com/">YAMLLint</a> to check if your YAML syntax is correct before loading it into Home Assistant which will save you some time. If you do so, be aware that this is a third-party service and is not maintained by the Home Assistant community.</p>
<p class="note">
Please pay attention on not storing private data (passwords, API keys, etc.) directly in your <code class="highlighter-rouge">configuration.yaml</code> file. Private data can be stored in a <a href="/docs/configuration/secrets/">separate file</a> or in <a href="/docs/configuration/yaml/#using-environment-variables">environmental variables</a>, which circumvents this problem of security.
</p>
<p>Text following a <code class="highlighter-rouge">#</code> are comments and are ignored by the system.</p>
<p>The next example shows an <a href="/components/input_select">input_select</a> component that uses a block collection for the options values.
The other properties (like name) are specified using mappings. Note that the second line just has <code class="highlighter-rouge">threat:</code> with no value on the same line. Here threat is the name of the input_select and the values for it are everything nested below it.</p>
<div class="language-yaml highlighter-rouge"><pre class="highlight"><code><span class="s">input_select</span><span class="pi">:</span>
<span class="s">threat</span><span class="pi">:</span>
<span class="s">name</span><span class="pi">:</span> <span class="s">Threat level</span>
<span class="c1"># A collection is used for options</span>
<span class="s">options</span><span class="pi">:</span>
<span class="pi">-</span> <span class="s">0</span>
<span class="pi">-</span> <span class="s">1</span>
<span class="pi">-</span> <span class="s">2</span>
<span class="pi">-</span> <span class="s">3</span>
<span class="s">initial</span><span class="pi">:</span> <span class="s">0</span>
</code></pre>
</div>
<p>The following example shows nesting a collection of mappings in a mapping. In Home Assistant, this would create two sensors that each use the MQTT platform but have different values for their <code class="highlighter-rouge">state_topic</code> (one of the properties used for MQTT sensors).</p>
<div class="language-yaml highlighter-rouge"><pre class="highlight"><code><span class="s">sensor</span><span class="pi">:</span>
<span class="pi">-</span> <span class="s">platform</span><span class="pi">:</span> <span class="s">mqtt</span>
<span class="s">state_topic</span><span class="pi">:</span> <span class="s">sensor/topic</span>
<span class="pi">-</span> <span class="s">platform</span><span class="pi">:</span> <span class="s">mqtt</span>
<span class="s">state_topic</span><span class="pi">:</span> <span class="s">sensor2/topic</span>
</code></pre>
</div>
<h3><a class="title-link" name="using-environment-variables" href="#using-environment-variables"></a> Using Environment Variables</h3>
<p>You can include values from your system’s environment variables with <code class="highlighter-rouge">!env_var</code>.</p>
<div class="language-yaml highlighter-rouge"><pre class="highlight"><code><span class="s">http</span><span class="pi">:</span>
<span class="s">api_password</span><span class="pi">:</span> <span class="kt">!env_var</span> <span class="s">PASSWORD</span>
</code></pre>
</div>
<h4>Default Value</h4>
<p>If an environment variable is not set, you can fallback to a default value.</p>
<div class="language-yaml highlighter-rouge"><pre class="highlight"><code><span class="s">http</span><span class="pi">:</span>
<span class="s">api_password</span><span class="pi">:</span> <span class="kt">!env_var</span> <span class="s">PASSWORD default_password</span>
</code></pre>
</div>
<h3><a class="title-link" name="including-separate-files" href="#including-separate-files"></a> Including Separate Files</h3>
<p>To improve readability, you can source out certain domains from your main configuration file with the <code class="highlighter-rouge">!include</code>-syntax.</p>
<div class="language-yaml highlighter-rouge"><pre class="highlight"><code><span class="s">lights</span><span class="pi">:</span> <span class="kt">!include</span> <span class="s">lights.yaml</span>
</code></pre>
</div>
<p>More information about this feature can also be found at <a href="/docs/configuration/splitting_configuration/">splitting configuration</a>.</p>
</article>
</div>
<aside id="sidebar" class="grid__item one-third lap-one-whole palm-one-whole">
<div class="grid">
<section class="aside-module grid__item one-whole lap-one-half">
<div class='section'>
<h1 class="title delta">Topics</h1>
<ul class='divided sidebar-menu'>
<li>
<b><a href='/faq/'>FAQ </a></b> |
<b><a href='/docs/glossary/'>Glossary </a></b>
</li>
<li>
<b><a href='/docs/installation/'>Installation </a></b>
<ul>
<li><a href='/hassio/'>Hass.io </a></li>
<li><a href='/docs/installation/virtualenv/'>Python Virtual Env </a></li>
<li><a href='/docs/installation/hassbian/'>Hassbian </a></li>
<!--<li><a href='/docs/installation/raspberry-pi-all-in-one/'>Raspberry Pi All-in-One </a></li>-->
<li><a href='/docs/installation/updating/'>Updating </a></li>
<li><a href='/docs/installation/troubleshooting/'>Troubleshooting </a></li>
</ul>
</li>
<li>
<b><a href='/docs/configuration/'>Configuration </a></b>
<ul>
<li><a class='active' href='/docs/configuration/yaml/'>YAML </a></li>
<li><a href='/docs/configuration/basic/'>Basic information </a></li>
<li><a href='/docs/configuration/devices/'>Setting up devices </a></li>
<li><a href='/docs/configuration/customizing-devices/'>Customizing entities </a></li>
<li><a href='/docs/configuration/troubleshooting/'>Troubleshooting </a></li>
<li><a href='/docs/configuration/securing/'>Security Check Points </a></li>
</ul>
</li>
<li>
<b>Advanced Configuration</b>
<ul>
<li><a href='/docs/configuration/remote/'>Remote access </a></li>
<li><a href='/docs/configuration/packages/'>Packages </a></li>
<li><a href='/docs/configuration/splitting_configuration/'>Splitting up the configuration </a></li>
<li><a href='/docs/configuration/secrets/'>Storing Secrets </a></li>
<li><a href='/docs/configuration/templating/'>Templating </a></li>
<li><a href='/docs/configuration/group_visibility/'>Group Visibility </a></li>
<li><a href='/docs/configuration/platform_options/'>Entity component platform options </a></li>
</ul>
</li>
<li>
<b>Core objects</b>
<ul>
<li><a href='/docs/configuration/events/'>Events </a></li>
<li><a href='/docs/configuration/state_object/'>State Objects </a></li>
</ul>
</li>
<li>
<b><a href='/docs/automation/'>Automation </a></b>
<ul>
<li><a href='/docs/automation/examples/'>Examples </a></li>
<li><a href='/docs/automation/editor/'>Editor </a></li>
<li><a href='/docs/automation/trigger/'>Triggers </a></li>
<li><a href='/docs/automation/condition/'>Conditions </a></li>
<li><a href='/docs/automation/action/'>Actions </a></li>
<li><a href='/docs/automation/templating/'>Templates </a></li>
</ul>
</li>
<li>
<b><a href='/docs/frontend/'>Frontend </a></b>
<ul>
<li><a href='/docs/frontend/mobile/'>Android/iOS Homescreen </a></li>
<li><a href='/docs/frontend/webserver/'>Web server fingerprint </a></li>
<li><a href='/docs/frontend/browsers/'>Browser Compatibility List </a></li>
</ul>
</li>
<li>
<b><a href='/docs/backend/'>Backend </a></b>
<ul>
<li><a href='/docs/backend/database/'>Database </a></li>
<li><a href='/docs/backend/updater/'>Updater </a></li>
<li><a href='/developers/api/'>API </a></li>
</ul>
</li>
<li>
<b><a href='/docs/scripts/'>Scripts </a></b>
<ul>
<li><a href='/docs/scripts/service-calls/'>Service Calls </a></li>
<li><a href='/docs/scripts/conditions/'>Conditions </a></li>
<li><a href='/docs/scripts/editor/'>Editor </a></li>
</ul>
</li>
<li>
<b><a href='/docs/tools/'>Tools and Helpers </a></b>
<ul>
<li><a href='/docs/tools/dev-tools/'>Developer Tools </a></li>
<li><a href='/docs/tools/hass/'>hass </a></li>
<li><a href='/docs/tools/benchmark/'>benchmark </a></li>
<li><a href='/docs/tools/check_config/'>check_config </a></li>
<li><a href='/docs/tools/credstash/'>credstash </a></li>
<li><a href='/docs/tools/db_migrator/'>db_migrator </a></li>
<li><a href='/docs/tools/ensure_config/'>ensure_config </a></li>
<li><a href='/docs/tools/influxdb_import/'>influxdb_import </a></li>
<li><a href='/docs/tools/influxdb_migrator/'>influxdb_migrator </a></li>
<li><a href='/docs/tools/keyring/'>keyring </a></li>
</ul>
</li>
<li>
<b><a href='/docs/z-wave/'>Z-Wave </a></b>
<ul>
<li><a href='/docs/z-wave/installation/'>Configuring the Z-Wave component </a></li>
<li><a href='/docs/z-wave/adding/'>Adding devices </a></li>
<li><a href='/docs/z-wave/control-panel/'>The Z-Wave control panel </a></li>
<li><a href='/docs/z-wave/controllers/'>Controllers </a></li>
<li><a href='/docs/z-wave/devices/'>Devices </a> and <a href='/docs/z-wave/entities/'>Entities </a></li>
<li><a href='/docs/z-wave/query-stage/'>Query Stages </a> for devices</li>
<li><a href='/docs/z-wave/device-specific/'>Device Specific </a> configuration</li>
<li><a href='/docs/z-wave/events/'>Events </a> and <a href='/docs/z-wave/services/'>Services </a></li>
</ul>
</li>
<li>
<b><a href='/docs/mqtt/'>MQTT </a></b>
<ul>
<li><a href='/docs/mqtt/broker/'>Broker </a></li>
<li><a href='/docs/mqtt/certificate/'>Certificate </a></li>
<li><a href='/docs/mqtt/discovery/'>Discovery </a></li>
<li><a href='/docs/mqtt/service/'>Publish service </a></li>
<li><a href='/docs/mqtt/birth_will/'>Birth and last will messages </a></li>
<li><a href='/docs/mqtt/testing/'>Testing your setup </a></li>
<li><a href='/docs/mqtt/logging/'>Logging </a></li>
<li><a href='/docs/mqtt/processing_json/'>Processing JSON </a></li>
</ul>
</li>
<li>
<b><a href='/docs/ecosystem/ios/'>iOS </a></b>
<ul>
<li><a href='/docs/ecosystem/ios/notifications/basic/'>Basic notifications </a></li>
<ul>
<li><a href='/docs/ecosystem/ios/notifications/sounds/'>Sounds </a></li>
<li><a href='/docs/ecosystem/ios/notifications/architecture/'>Architecture </a></li>
<li><a href='/docs/ecosystem/ios/notifications/privacy_security_rate_limits/'>Privacy, rate limiting and security </a></li>
</ul>
<li>Advanced notifications</li>
<ul>
<li><a href='/docs/ecosystem/ios/notifications/attachments/'>Attachments </a></li>
<li><a href='/docs/ecosystem/ios/notifications/content_extensions/'>Dynamic content </a></li>
<li><a href='/docs/ecosystem/ios/notifications/actions/'>Actionable notifications </a></li>
<li><a href='/docs/ecosystem/ios/notifications/requesting_location_updates/'>Requesting location updates </a></li>
</ul>
<li><a href='/docs/ecosystem/ios/location/'>Location Tracking </a></li>
<li><a href='/docs/ecosystem/ios/integration/'>Integration with other apps </a></li>
</ul>
</li>
<li>
<a href='/docs/ecosystem/'>Ecosystem </a>
<ul>
<li>
<a href='/docs/autostart/'>Autostart </a>
<ul>
<li><a href='/docs/autostart/systemd/'>systemd (Linux) </a></li>
<li><a href='/docs/autostart/upstart/'>Upstart (Linux) </a></li>
<li><a href='/docs/autostart/init.d/'>init.d (Linux) </a></li>
<li><a href='/docs/autostart/macos/'>macOS </a></li>
<li><a href='/docs/autostart/synology/'>Synology NAS </a></li>
</ul>
</li>
<li>
<a href='/docs/ecosystem/appdaemon/'>AppDaemon </a>
</li>
<li>
<a href='/docs/ecosystem/hadashboard/'>HADashboard </a>
</li>
<li>
<a href='/docs/ecosystem/notebooks/'>Notebooks </a>
<ul>
<li><a href='/docs/ecosystem/notebooks/'>Introduction </a></li>
<li><a href='/docs/ecosystem/notebooks/installation/'>Installation </a></li>
<li><a href='/docs/ecosystem/notebooks/graph/'>Graph </a></li>
<li><a href='/docs/ecosystem/notebooks/api/'>Home Assistant API </a></li>
<li><a href='/docs/ecosystem/notebooks/database/'>Database </a></li>
<li><a href='/docs/ecosystem/notebooks/stats/'>Statistics </a></li>
</ul>
</li>
<li>
Remote access
<ul>
<li><a href='/docs/ecosystem/apache/'>Apache </a></li>
<li><a href='/docs/ecosystem/caddy/'>Caddy Server </a></li>
<li><a href='/docs/ecosystem/nginx/'>NGINX </a></li>
<li><a href='/docs/ecosystem/nginx_subdomain/'>NGINX with subdomain</a></li>
<li><a href='/docs/ecosystem/tor/'>Tor Onion Service </a></li>
</ul>
</li>
<li>
<a href='/docs/ecosystem/certificates/'>Certificates </a>
<ul>
<li><a href='/docs/ecosystem/certificates/tls_self_signed_certificate/'>Self-signed certificate </a></li>
<li><a href='/docs/ecosystem/certificates/tls_domain_certificate/'>Certificate domain owners </a></li>
<li><a href='/docs/ecosystem/certificates/lets_encrypt/'>Let's Encrypt (detailed) </a></li>
</ul>
</li>
<li>
Backup
<ul>
<li><a href='/docs/ecosystem/backup/backup_github/'>Backup to GitHub </a></li>
<li><a href='/docs/ecosystem/backup/backup_dropbox/'>Backup to Dropbox </a></li>
<li><a href='/docs/ecosystem/backup/backup_usb/'>Backup to USB device </a></li>
</ul>
</li>
<li><a href='/docs/ecosystem/scenegen/'>scenegen </a></li>
<li><a href='/docs/ecosystem/synology/'>Synology </a></li>
<li><a href='/docs/ecosystem/hass-configurator/'>HASS Configurator </a></li>
</ul>
</ul>
</div>
</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://facebook.com/homeassistantio'><i class="icon-facebook"></i></a>
<a rel="me" href='https://plus.google.com/110560654828510104551'><i class="icon-google-plus"></i></a>
<a rel="me" href='https://github.com/home-assistant/home-assistant'><i class="icon-github"></i></a>
<div class="credit">
Contact us at <a href='mailto:hello@home-assistant.io'>hello@home-assistant.io</a> (no support!).<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>
<a rel="license" href="http://creativecommons.org/licenses/by-nc-sa/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by-nc-sa/4.0/88x31.png" /></a><br /><span xmlns:dct="http://purl.org/dc/terms/" property="dct:title">home-assistant.io</span> is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by-nc-sa/4.0/">Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License</a>.
</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>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/docsearch.js/2/docsearch.min.css" />
<script type="text/javascript" src="https://cdn.jsdelivr.net/docsearch.js/2/docsearch.min.js"></script>
<script type="text/javascript">
docsearch({
apiKey: 'ae96d94b201c5444c8a443093edf3efb',
indexName: 'home-assistant',
inputSelector: '#search',
debug: false // Set debug to true if you want to inspect the dropdown
});
document.querySelector('.search .close').addEventListener('click', function(ev) {
ev.preventDefault();
document.querySelector('.search-container').style.display = 'none';
});
document.querySelector('.show-search').addEventListener('click', function(ev) {
ev.preventDefault();
document.querySelector('.search-container').style.display = 'block';
document.getElementById('toggle').checked = false;
document.querySelector('.search-container input').focus();
});
</script>
</body>
</html>
Reference in a new issue View git blame Copy permalink