242 lines
No EOL
12 KiB
HTML
242 lines
No EOL
12 KiB
HTML
<!doctype html>
|
||
<!--[if lt IE 7]> <html class="no-js lt-ie9 lt-ie8 lt-ie7"> <![endif]-->
|
||
<!--[if IE 7]> <html class="no-js lt-ie9 lt-ie8"> <![endif]-->
|
||
<!--[if IE 8]> <html class="no-js lt-ie9"> <![endif]-->
|
||
<!--[if gt IE 8]><!--> <html> <!--<![endif]-->
|
||
|
||
<head>
|
||
<meta charset="utf-8">
|
||
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
|
||
<title>Creating components - Home Assistant</title>
|
||
<meta name="author" content="Paulus Schoutsen">
|
||
<meta name="description" content="Guidelines to get you create your first component for Home Assistant.">
|
||
|
||
<meta name="viewport" content="width=device-width">
|
||
<link rel="canonical" href="https://home-assistant.io/developers/creating_components/">
|
||
|
||
<meta property="fb:app_id" content="338291289691179">
|
||
<meta property="og:title" content="Creating components">
|
||
<meta property="og:site_name" content="Home Assistant">
|
||
<meta property="og:url" content="https://home-assistant.io/developers/creating_components/">
|
||
<meta property="og:type" content="website">
|
||
<meta property="og:description" content="Guidelines to get you create your first component for Home Assistant.">
|
||
<meta property="og:image" content="https://home-assistant.io/images/home-assistant-logo-2164x2164.png">
|
||
|
||
<meta name="twitter:card" content="summary_large_image">
|
||
<meta name="twitter:site" content="@balloob">
|
||
<meta name="twitter:title" content="Creating components">
|
||
<meta name="twitter:description" content="Guidelines to get you create your first component for Home Assistant.">
|
||
<meta name="twitter:image" content="https://home-assistant.io/images/home-assistant-logo-2164x2164.png">
|
||
|
||
<link href="/stylesheets/screen.css" media="screen, projection" rel="stylesheet">
|
||
<link href="/atom.xml" rel="alternate" title="Home Assistant" type="application/atom+xml">
|
||
<link rel='shortcut icon' href='/images/favicon.ico' />
|
||
<link rel='icon' type='image/png' href='/images/favicon-192x192.png' sizes='192x192' />
|
||
</head>
|
||
|
||
<body >
|
||
|
||
<header>
|
||
<div class="grid-wrapper">
|
||
<div class="grid">
|
||
|
||
<div class="grid__item three-tenths lap-two-sixths palm-one-whole ha-title">
|
||
<a href="/" class="site-title">
|
||
<img width='40' src='/images/favicon-192x192.png'> Home Assistant
|
||
</a>
|
||
</div>
|
||
|
||
<div class="grid__item seven-tenths lap-four-sixths palm-one-whole">
|
||
<nav>
|
||
<input type="checkbox" id="toggle">
|
||
<label for="toggle" class="toggle" data-open="Main Menu" data-close="Close Menu"></label>
|
||
<ul class="menu pull-right">
|
||
<li>
|
||
<a href="/getting-started/">Getting started</a>
|
||
<ul>
|
||
<li><a href='/getting-started/'>Installing Home Assistant</a></li>
|
||
<li><a href='/getting-started/configuration/'>Configuration basics</a></li>
|
||
<li><a href='/getting-started/devices/'>Adding devices</a></li>
|
||
<li><a href='/getting-started/presence-detection/'>Presence detection</a></li>
|
||
<li><a href='/getting-started/automation/'>Automation</a></li>
|
||
<li><a href='/cookbook'>Configuration cookbook</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href='/components/'>Components</a></li>
|
||
<li>
|
||
<a href="/developers/">Developers</a>
|
||
<ul>
|
||
<li><a href="/developers/architecture/">Architecture</a></li>
|
||
<li><a href="/developers/frontend/">Frontend development</a></li>
|
||
<li><a href="/developers/creating_components/">
|
||
Creating components
|
||
</a></li>
|
||
<li><a href="/developers/add_new_platform/">
|
||
Adding platform support
|
||
</a></li>
|
||
<li><a href="/developers/api/">API</a></li>
|
||
<li><a href="/developers/credits/">Credits</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="/blog/">Blog</a></li>
|
||
<li><a href="/help/">Need help?</a></li>
|
||
</ul>
|
||
</nav>
|
||
</div>
|
||
|
||
</div>
|
||
</div>
|
||
</header>
|
||
|
||
|
||
|
||
<div class="grid-wrapper">
|
||
<div class="grid grid-center">
|
||
|
||
<div class="grid__item two-thirds lap-one-whole palm-one-whole">
|
||
|
||
|
||
<article class="page">
|
||
|
||
|
||
<header>
|
||
<h1 class="title indent">
|
||
Creating Components
|
||
</h1>
|
||
</header>
|
||
<hr class="divider">
|
||
|
||
|
||
<p>Home Assistant offers <a href="/components/">built-in components</a> but it is easy to built your own. If you are the kind of person that likes to learn from code rather then guide then head over to the <a href="https://github.com/balloob/home-assistant/tree/master/config/custom_components"><code>config/custom_components</code></a> folder in the repository for two example components.</p>
|
||
|
||
<p>The first is <a href="https://github.com/balloob/home-assistant/blob/master/config/custom_components/hello_world.py">hello_world.py</a>, which is the classic Hello World example for Home Assistant. The second one is <a href="https://github.com/balloob/home-assistant/blob/master/config/custom_components/example.py">example.py</a> which showcases various ways you can tap into Home Assistant to be notified when certain events occur.</p>
|
||
|
||
<p>If you want to load these components in Home Assistant, add the following lines to your <code>configuration.yaml</code> file:</p>
|
||
|
||
<div class="highlighter-coderay"><div class="CodeRay">
|
||
<div class="code"><pre><span class="key">hello_world</span>:
|
||
|
||
<span class="key">example</span>:
|
||
<span class="key">target</span>: <span class="string"><span class="content">TARGET_ENTITY</span></span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
|
||
<p><code>TARGET_ENTITY</code> should be one of your devices that can be turned on and off, ie a light or a switch. Example value could be <code>light.Ceiling</code> or <code>switch.AC</code> (if you have these devices with those names).</p>
|
||
|
||
<h2><a class="title-link" name="loading-components" href="#loading-components"></a> Loading components</h2>
|
||
|
||
<p>A component will be loaded on start if a section (ie. <code>light:</code>) for it exists in the config file. A component can also be loaded if another component is loaded that depends on it. When loading a component Home Assistant will check the following paths:</p>
|
||
|
||
<ul>
|
||
<li><code><config directory>/custom_components/<component name></code></li>
|
||
<li><code>homeassistant/components/<component name></code> (built-in components)</li>
|
||
</ul>
|
||
|
||
<p>Once loaded, a component will only be setup if all dependencies can be loaded and are able to setup. Keep an eye on the logs to see if your component could be loaded and initialized.</p>
|
||
|
||
<p class="note warning">
|
||
You can override a built-in component by having a component with the same name in your <code>config/custom_components</code> folder. This is not recommended and will probably break things!
|
||
</p>
|
||
|
||
<p class="note">
|
||
Home Assistant will use the directory that contains your config file as the directory that holds your customizations. By default this is the <code>config</code> folder in your current work directory. You can use a different folder by running Home Assistant with the –config argument: <code>python3 homeassistant --config /YOUR/CONFIG/PATH/</code>.
|
||
</p>
|
||
|
||
<h2><a class="title-link" name="dependencies" href="#dependencies"></a> Dependencies</h2>
|
||
|
||
<p>Home Assistant allows components and platforms to specify their dependencies and requirements using the variables <code>DEPENDENCIES</code> and <code>REQUIREMENTS</code>. Both are lists that contain strings.</p>
|
||
|
||
<p>Dependencies are other Home Assistant components that should be setup before the platform is loaded. An example is the MQTT sensor component, which requires an active connection to an MQTT broker. If Home Assistant is unable to load and setup the MQTT component, it will not setup the MQTT sensor component.</p>
|
||
|
||
<p>Requirements are Python libraries that you would normally install using <code>pip</code>. Each entry in a requirement list is a pip compatible string. For example, the media player Cast platform depends on the Python package PyChromecast thus <code>REQUIREMENTS = ['pychromecast==0.6.12']</code>. If Home Assistant is unable to install the package or verify it is installed, the component will fail to load.</p>
|
||
|
||
<h2><a class="title-link" name="initializing-components" href="#initializing-components"></a> Initializing components</h2>
|
||
|
||
<p>After loading, the bootstrapper will call <code>setup(hass, config)</code> method on the component to initialize it.</p>
|
||
|
||
<h3><a class="title-link" name="hass-the-home-assistant-instance" href="#hass-the-home-assistant-instance"></a> <code>hass</code>: the Home Assistant instance</h3>
|
||
|
||
<p>The Home Assistant instace contains three objects to help you interact with the system.</p>
|
||
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Object</th>
|
||
<th>Description</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td><code>hass.config</code></td>
|
||
<td>This is the core configuration of Home Assistant exposing location, temperature preferences and config directory path. <a href="https://github.com/balloob/home-assistant/blob/dev/homeassistant/core.py#L687">Details</a></td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>hass.states</code></td>
|
||
<td>This is the StateMachine. It allows you to set states and track when they are changed. <a href="https://github.com/balloob/home-assistant/blob/dev/homeassistant/core.py#L434">See available methods</a>.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>hass.bus</code></td>
|
||
<td>This is the EventBus. It allows you to trigger and listen for events.<br /><a href="https://github.com/balloob/home-assistant/blob/dev/homeassistant/core.py#L229">See available methods</a>.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><code>hass.services</code></td>
|
||
<td>This is the ServiceRegistry. It allows you to register services.<br /><a href="https://github.com/balloob/home-assistant/blob/dev/homeassistant/core.py#L568">See available methods</a>.</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
|
||
<h3><a class="title-link" name="config-user-given-configuration" href="#config-user-given-configuration"></a> <code>config</code>: User given configuration.</h3>
|
||
|
||
<p>The <code>config</code> paramter is a dictionary containing the user supplied configuration. The keys of the dictionary are the component names and the value is another dictionary with the component configuration.</p>
|
||
|
||
<p>If your configuration file contains the following lines:</p>
|
||
|
||
<div class="highlighter-coderay"><div class="CodeRay">
|
||
<div class="code"><pre><span class="key">example</span>:
|
||
<span class="key">host</span>: <span class="string"><span class="content">paulusschoutsen.nl</span></span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
|
||
<p>Then in the setup method of your component you will be able to refer to <code>config['example']['host']</code> to get the value <code>paulusschoutsen.nl</code>.</p>
|
||
|
||
<h2><a class="title-link" name="responding-to-events" href="#responding-to-events"></a> Responding to events</h2>
|
||
|
||
<p>Home Assistant has different ways of responding to events that occur in Home Assistant. These have been organized in <a href="https://github.com/balloob/home-assistant/blob/dev/homeassistant/helpers/event.py">helper methods</a>. Examples are <code>track_state_change</code>, <code>track_point_in_time</code>, <code>track_time_change</code>.</p>
|
||
|
||
|
||
</article>
|
||
|
||
|
||
</div>
|
||
|
||
|
||
</div>
|
||
</div>
|
||
|
||
<footer>
|
||
<div class="grid-wrapper">
|
||
<div class="grid">
|
||
<div class="grid__item">
|
||
<p class="copyright">
|
||
<span class="credit">Powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>. Hosted by <a href='https://pages.github.com/'>GitHub</a> and served by <a href='https://cloudflare.com'>CloudFlare</a>.</span>
|
||
</p>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</footer>
|
||
|
||
<!--[if lt IE 7]>
|
||
<p class="chromeframe">You are using an <strong>outdated</strong> browser. Please <a href="http://browsehappy.com/">upgrade your browser</a> or <a href="http://www.google.com/chromeframe/?redirect=true">activate Google Chrome Frame</a> to improve your experience.</p>
|
||
<![endif]-->
|
||
|
||
<script>
|
||
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
|
||
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
|
||
g.src=('https:'==location.protocol?'//ssl':'//www')+'.google-analytics.com/ga.js';
|
||
s.parentNode.insertBefore(g,s)}(document,'script'));
|
||
</script>
|
||
|
||
</body>
|
||
</html> |