263 lines
No EOL
13 KiB
HTML
263 lines
No EOL
13 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>Adding support for a new platform - Home Assistant</title>
|
|
<meta name="author" content="Paulus Schoutsen">
|
|
|
|
<meta name="description" content="Hints and tips for when you're adding a new platform to Home Assistant.">
|
|
|
|
<meta name="viewport" content="width=device-width">
|
|
<link rel="canonical" href="https://home-assistant.io/developers/add_new_platform.html">
|
|
|
|
<meta property="fb:app_id" content="338291289691179">
|
|
<meta property="og:title" content="Adding support for a new platform">
|
|
<meta property="og:site_name" content="Home Assistant">
|
|
<meta property="og:url" content="https://home-assistant.io/developers/add_new_platform.html/">
|
|
<meta property="og:type" content="website">
|
|
<meta property="og:description" content="Hints and tips for when you're adding a new platform to Home Assistant.">
|
|
<meta property="og:image" content="https://home-assistant.io/images/home-assistant-logo-2164x2164.png">
|
|
|
|
<link href="/stylesheets/screen.css" media="screen, projection" rel="stylesheet">
|
|
<link href="/atom.xml" rel="alternate" title="Home Assistant" type="application/atom+xml">
|
|
<link rel='shortcut icon' href='/images/favicon.ico' />
|
|
<link rel='icon' type='image/png' href='/images/favicon-192x192.png' sizes='192x192' />
|
|
</head>
|
|
|
|
|
|
<body >
|
|
|
|
<header>
|
|
<div class="grid-wrapper">
|
|
<div class="grid">
|
|
|
|
<div class="grid__item three-tenths lap-two-sixths palm-one-whole ha-title">
|
|
<a href="/" class="site-title">
|
|
<img width='40' src='/images/favicon-192x192.png'> Home Assistant
|
|
</a>
|
|
</div>
|
|
|
|
<div class="grid__item seven-tenths lap-four-sixths palm-one-whole">
|
|
<nav>
|
|
<input type="checkbox" id="toggle">
|
|
<label for="toggle" class="toggle" data-open="Main Menu" data-close="Close Menu"></label>
|
|
<ul class="menu pull-right">
|
|
<li>
|
|
<a href="/getting-started/">Getting started</a>
|
|
<ul>
|
|
<li><a href='/getting-started/'>Installing Home Assistant</a></li>
|
|
<li><a href='/getting-started/configuration.html'>Configuration basics</a></li>
|
|
<li><a href='/getting-started/devices.html'>Adding devices</a></li>
|
|
<li><a href='/getting-started/presence-detection.html'>Presence detection</a></li>
|
|
<li><a href='/getting-started/automation.html'>Automation</a></li>
|
|
<li><a href='/components/'>Component overview</a></li>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
<a href="/developers/">Developers</a>
|
|
<ul>
|
|
<li><a href="/developers/architecture.html">Architecture</a></li>
|
|
<li><a href="/developers/frontend.html">Frontend development</a></li>
|
|
<li><a href="/developers/creating_components.html">
|
|
Creating components
|
|
</a></li>
|
|
<li><a href="/developers/add_new_platform.html">
|
|
Adding platform support
|
|
</a></li>
|
|
<li><a href="/developers/api.html">API</a></li>
|
|
<li><a href="/developers/credits.html">Credits</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="/blog/">Blog</a></li>
|
|
<li><a href="/help/">Need help?</a></li>
|
|
</ul>
|
|
|
|
</nav>
|
|
</div>
|
|
|
|
|
|
</div>
|
|
</div>
|
|
</header>
|
|
|
|
|
|
|
|
<div class="grid-wrapper">
|
|
<div class="grid grid-center">
|
|
|
|
<div class="grid__item two-thirds lap-one-whole palm-one-whole">
|
|
|
|
|
|
<article class="page">
|
|
|
|
|
|
<header>
|
|
<h1 class="title indent">
|
|
Adding Support for a New Platform
|
|
</h1>
|
|
</header>
|
|
<hr class="divider">
|
|
|
|
|
|
<p>Components that interact with devices are structured in core- and platform logic. This allows the same logic to be used for different platforms.</p>
|
|
|
|
<p>For example, the built-in <code>switch</code> component consists of the following files in <a href="https://github.com/balloob/home-assistant/tree/master/homeassistant/components/switch"><code>homeassistant/components/switch/</code></a>:</p>
|
|
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th> File </th>
|
|
<th> Description </th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td> __init__.py </td>
|
|
<td> Contains the Switch core logic.</td>
|
|
</tr>
|
|
<tr>
|
|
<td> wemo.py </td>
|
|
<td> WeMo platform logic. Included if in config <code>platform=wemo</code>. </td>
|
|
</tr>
|
|
<tr>
|
|
<td> tellstick.py </td>
|
|
<td> Tellstick platform logic. Included if in config <code>platform=tellstick</code>. </td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
|
|
<p>If you are planning to add support for a new type of device to an existing component, you can get away with only writing platform logic. Have a look at how the component works with other platforms and create a similar file for the platform that you would like to add.</p>
|
|
|
|
<h3><a class='title-link' name='interfacing-with-devices' href='#interfacing-with-devices'></a> Interfacing with devices</h3>
|
|
|
|
<p>One of the rules for Home Assistant is that platform logic should never interface directly with
|
|
devices but use a third-party Python 3 library to do so. This way Home Assistant is able to share
|
|
code with the Python community and we can keep the project maintainable.</p>
|
|
|
|
<p>Platforms can specify dependencies and requirements the same way as a component does. Please see
|
|
<a href="/developers/creating_components.html#dependencies">the component page</a> for more information.</p>
|
|
|
|
<h3><a class='title-link' name='creating-entities' href='#creating-entities'></a> Creating Entities</h3>
|
|
|
|
<p>Home Assistant will call a function with the following signature to initialize
|
|
your new platform. This function must exist in the platform module you create.</p>
|
|
|
|
<figure class='code'><figcaption><span></span></figcaption><div class="highlight"><table><tr><td class="gutter"><pre class="line-numbers"><span class='line-number'>1</span>
|
|
</pre></td><td class='code'><pre><code class='python'><span class='line'><span class="k">def</span> <span class="nf">setup_platform</span><span class="p">(</span><span class="n">hass</span><span class="p">,</span> <span class="n">config</span><span class="p">,</span> <span class="n">add_devices</span><span class="p">,</span> <span class="n">discovery_info</span><span class="o">=</span><span class="bp">None</span><span class="p">)</span>
|
|
</span></code></pre></td></tr></table></div></figure>
|
|
|
|
|
|
<p>In this function, your platform should create the appropriate entities and
|
|
register them with the Home Assistant core. Entities are Home Assistant’s
|
|
representation of lights, switches, sensors, etc. and are derived from the
|
|
<a href="https://github.com/balloob/home-assistant/blob/master/homeassistant/helpers/entity.py">Entity Abstract Class</a>.
|
|
This abstract class contains logic for integrating most standard features into
|
|
your entities, such as visibility, entity IDs, updates, and many more.</p>
|
|
|
|
<p>A list of entities can be registered with Home Assistant using the <em>add_devices</em>
|
|
function that is provided as an input to <em>setup_platform</em>. Once entities are
|
|
registered with with Home Assistant their updates will be provided to the core
|
|
and the core will have control over them. For more information on how Entities
|
|
can be customized, take a look at the <a href="https://github.com/balloob/home-assistant/blob/master/homeassistant/helpers/entity.py#L18">Entity Abstract
|
|
Class</a>.</p>
|
|
|
|
<h2><a class='title-link' name='allowing-your-platform-to-be-discovered' href='#allowing-your-platform-to-be-discovered'></a> Allowing your platform to be discovered</h2>
|
|
|
|
<p>Home Assistant has a discovery service running in the background to discover new devices. Whenever a new device is discovered, an <code>SERVICE_DISCOVERED</code> event will be fired with the found service and the information. The <code>discovery</code> component has some knowledge about which components handle which type of services and will ensure those are loaded and listening before firing the <code>SERVICE_DISCOVERED</code> event.</p>
|
|
|
|
<h3><a class='title-link' name='add-discovery-instructions' href='#add-discovery-instructions'></a> Add discovery instructions</h3>
|
|
|
|
<p>Device discovery for Home Assistant has been extracted into an external library called <a href="https://github.com/balloob/netdisco">NetDisco</a>. This library is integrated using <a href="https://github.com/balloob/home-assistant/blob/dev/homeassistant/components/discovery.py">the <code>discovery</code> component</a> and scans the network in intervals for uPnP and zeroconf/mDNS services.</p>
|
|
|
|
<p>To have your device be discovered, you will have to extend the NetDisco library to be able to find your device. This is done by adding a new discoverable. <a href="https://github.com/balloob/netdisco/tree/master/netdisco/discoverables">See the repository for examples of existing discoverables.</a></p>
|
|
|
|
<h3><a class='title-link' name='listening-to-service_discovered-events' href='#listening-to-service_discovered-events'></a> Listening to <code>SERVICE_DISCOVERED</code> events</h3>
|
|
|
|
<p>From your component, you will have to set up the listening for specific services. Below an example how one would listen for discovered Chromecasts:</p>
|
|
|
|
<figure class='code'><figcaption><span></span></figcaption><div class="highlight"><table><tr><td class="gutter"><pre class="line-numbers"><span class='line-number'>1</span>
|
|
<span class='line-number'>2</span>
|
|
<span class='line-number'>3</span>
|
|
<span class='line-number'>4</span>
|
|
<span class='line-number'>5</span>
|
|
<span class='line-number'>6</span>
|
|
<span class='line-number'>7</span>
|
|
<span class='line-number'>8</span>
|
|
<span class='line-number'>9</span>
|
|
<span class='line-number'>10</span>
|
|
<span class='line-number'>11</span>
|
|
</pre></td><td class='code'><pre><code class='python'><span class='line'><span class="kn">from</span> <span class="nn">homeassistant.loader</span> <span class="kn">import</span> <span class="n">get_component</span>
|
|
</span><span class='line'>
|
|
</span><span class='line'><span class="k">def</span> <span class="nf">setup</span><span class="p">(</span><span class="n">hass</span><span class="p">,</span> <span class="n">config</span><span class="p">):</span>
|
|
</span><span class='line'> <span class="n">discovery</span> <span class="o">=</span> <span class="n">get_component</span><span class="p">(</span><span class="s">'discovery'</span><span class="p">)</span>
|
|
</span><span class='line'>
|
|
</span><span class='line'> <span class="k">def</span> <span class="nf">chromecast_discovered</span><span class="p">(</span><span class="n">service</span><span class="p">,</span> <span class="n">info</span><span class="p">):</span>
|
|
</span><span class='line'> <span class="sd">""" Called when a Chromecast has been discovered. """</span>
|
|
</span><span class='line'> <span class="k">print</span><span class="p">(</span><span class="s">"Discovered a new Chromecast: {}"</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">info</span><span class="p">))</span>
|
|
</span><span class='line'>
|
|
</span><span class='line'> <span class="n">discovery</span><span class="o">.</span><span class="n">listen</span><span class="p">(</span>
|
|
</span><span class='line'> <span class="n">hass</span><span class="p">,</span> <span class="n">discovery</span><span class="o">.</span><span class="n">services</span><span class="o">.</span><span class="n">GOOGLE_CAST</span><span class="p">,</span> <span class="n">chromecast_discovered</span><span class="p">)</span>
|
|
</span></code></pre></td></tr></table></div></figure>
|
|
|
|
|
|
<h3><a class='title-link' name='auto-loading-your-component-upon-discovery' href='#auto-loading-your-component-upon-discovery'></a> Auto-loading your component upon discovery</h3>
|
|
|
|
<p>The Discovery component is capable of setting up your components before firing the <code>SERVICE_DISCOVERD</code> event. To do this you will have to update the <a href="https://github.com/balloob/home-assistant/blob/dev/homeassistant/components/discovery.py#L29"><code>SERVICE_HANDLERS</code></a> constant in <a href="https://github.com/balloob/home-assistant/blob/dev/homeassistant/components/discovery.py">the <code>discovery</code> component</a>.</p>
|
|
|
|
<p class='note warning'>
|
|
This option is currently limited to built-in components.
|
|
</p>
|
|
|
|
|
|
|
|
</article>
|
|
|
|
|
|
</div>
|
|
|
|
|
|
</div>
|
|
</div>
|
|
|
|
<footer>
|
|
<div class="grid-wrapper">
|
|
<div class="grid">
|
|
<div class="grid__item">
|
|
<p class="copyright">
|
|
<span class="credit">Powered by <a href="http://octopress.org">Octopress</a>, <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>. Hosted by <a href='https://pages.github.com/'>GitHub</a> and served by <a href='https://cloudflare.com'>CloudFlare</a>.</span>
|
|
</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
</footer>
|
|
|
|
<!--[if lt IE 7]>
|
|
<p class="chromeframe">You are using an <strong>outdated</strong> browser. Please <a href="http://browsehappy.com/">upgrade your browser</a> or <a href="http://www.google.com/chromeframe/?redirect=true">activate Google Chrome Frame</a> to improve your experience.</p>
|
|
<![endif]-->
|
|
|
|
|
|
|
|
|
|
<script>
|
|
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
|
|
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
|
|
g.src=('https:'==location.protocol?'//ssl':'//www')+'.google-analytics.com/ga.js';
|
|
s.parentNode.insertBefore(g,s)}(document,'script'));
|
|
</script>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</body>
|
|
</html> |