230 lines
No EOL
8.5 KiB
HTML
230 lines
No EOL
8.5 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>Developers - Home Assistant</title>
|
|
<meta name="author" content="Paulus Schoutsen">
|
|
|
|
<meta name="description" content="Home Assistant is an open-source home automation platform running on Python 3.">
|
|
|
|
<meta name="viewport" content="width=device-width">
|
|
<link rel="canonical" href="https://home-assistant.io">
|
|
|
|
<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-four-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-two-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="/architecture/">Architecture</a></li>
|
|
<li><a href="/developers/">Developers</a></li>
|
|
<li><a href="/api/">API</a></li>
|
|
<li><a href="/blog/">Blog</a></li>
|
|
<li><a href="https://groups.google.com/forum/#!forum/home-assistant-dev">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">
|
|
Developers
|
|
</h1>
|
|
</header>
|
|
<hr class="divider">
|
|
|
|
|
|
<p>Home Assistant can be extended by components. Components can listen for- or trigger events and offer services. Components are written in Python and can do all the goodness that Python has to offer.</p>
|
|
|
|
<p>Home Assistant offers <a href="/components/">built-in components</a> but it is easy to built your own. An example component can be found in <a href="https://github.com/balloob/home-assistant/blob/master/config/custom_components/example.py"><code>/config/custom_components/example.py</code></a>.</p>
|
|
|
|
<div class='note'><p class='title'>Note</p><p class='content'>
|
|
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></div>
|
|
|
|
|
|
<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 loading and setup of your component went well.</p>
|
|
|
|
<div class='note warning'><p class='title'>Warning</p><p class='content'>
|
|
*Warning:* You can override a built-in component by offering a component with the same name in your custom_components folder. This is not recommended and may lead to unexpected behavior!
|
|
</p></div>
|
|
|
|
|
|
<p>Each component is responsible for a specific domain within Home Assistant. An example is the switch component, which is responsible for interaction with different types of switches. The switch component consists of the following files in <code>homeassistant/components/switch/</code>:</p>
|
|
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th> File </th>
|
|
<th> Description </th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td> __init__.py </td>
|
|
<td> Contains the Switch component code.</td>
|
|
</tr>
|
|
<tr>
|
|
<td> wemo.py </td>
|
|
<td> WeMo platform support. Included if in config <code>platform=wemo</code>. </td>
|
|
</tr>
|
|
<tr>
|
|
<td> tellstick.py </td>
|
|
<td> Tellstick platform support. Included if in config <code>platform=tellstick</code>. </td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
|
|
<p>If a component exists, your job is easy. Have a look at how the component works with other platforms and create a similar file for the platform that you would like to add. If you cannot find a suitable component, you’ll have to add it yourself. When writing a component try to structure it after the Switch component to maximize reusability.</p>
|
|
|
|
<p>Communication between Home Assistant and devices should happen via third-party libraries that implement the device API. This will make sure the platform support code stays as small as possible.</p>
|
|
|
|
<p>After a component is loaded the bootstrapper will call its setup method <code>setup(hass, config)</code>:</p>
|
|
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th> Parameter </th>
|
|
<th> Description </th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td> <code>hass</code> </td>
|
|
<td> The Home Assistant object. Call its methods to track time, register services or listen for events: <a href="https://github.com/balloob/home-assistant/blob/master/homeassistant/__init__.py#L38">Overview of available methods.</a> </td>
|
|
</tr>
|
|
<tr>
|
|
<td> <code>config</code> </td>
|
|
<td> A dict containing the configuration. The keys of the config-dict are component names and the value is another dict with configuration attributes. </td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
|
|
<h3>Guidance on using the Home Assistant object</h3>
|
|
|
|
<p>The Home Assistant object contains three objects to help you interact with the system.</p>
|
|
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th> Object </th>
|
|
<th> Description </th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td> <code>hass.states</code> </td>
|
|
<td> This is the StateMachine. The StateMachine allows you to see which states are available and set/test states for specified entities. <a href="https://github.com/balloob/home-assistant/blob/master/homeassistant/__init__.py#L473">See available methods</a>. </td>
|
|
</tr>
|
|
<tr>
|
|
<td> <code>hass.events</code> </td>
|
|
<td> This is the EventBus. The EventBus allows you to listen and trigger events. <a href="https://github.com/balloob/home-assistant/blob/master/homeassistant/__init__.py#L308">See available methods</a>. </td>
|
|
</tr>
|
|
<tr>
|
|
<td> <code>hass.services</code> </td>
|
|
<td> This is the ServiceRegistry. The ServiceRegistry allows you to register services. <a href="https://github.com/balloob/home-assistant/blob/master/homeassistant/__init__.py#L589">See available methods</a>. </td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
|
|
<h3>Example on using the configuration parameter</h3>
|
|
|
|
<p>If your configuration file containes the following lines:</p>
|
|
|
|
<figure class='code'><div class="highlight"><table><tr><td class="gutter"><pre class="line-numbers"><span class='line-number'>1</span>
|
|
<span class='line-number'>2</span>
|
|
</pre></td><td class='code'><pre><code class=''><span class='line'>[example]
|
|
</span><span class='line'>host=paulusschoutsen.nl</span></code></pre></td></tr></table></div></figure>
|
|
|
|
|
|
<p>Then in the setup-method of your component you will be able to refer to <code>config['example']['host']</code> to get the value <code>paulusschoutsen.nl</code>.</p>
|
|
|
|
|
|
</article>
|
|
|
|
|
|
</div>
|
|
|
|
|
|
</div>
|
|
</div>
|
|
|
|
<footer>
|
|
<div class="grid-wrapper">
|
|
<div class="grid">
|
|
<div class="grid__item">
|
|
<p class="copyright">
|
|
<span class="credit">Site powered by <a href="http://octopress.org">Octopress</a>, <a href='http://jekyllrb.com/'>Jekyll</a> and using the <a href='https://github.com/coogie/oscailte'>Oscalite theme</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]-->
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</body>
|
|
</html> |