222 lines
No EOL
12 KiB
HTML
222 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>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/">
|
||
|
||
<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/">
|
||
<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">
|
||
|
||
<meta name="twitter:card" content="summary">
|
||
<meta name="twitter:site" content="@home_assistant">
|
||
|
||
<meta name="twitter:title" content="Adding support for a new platform">
|
||
<meta name="twitter:description" content="Hints and tips for when you're adding a new platform to 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='/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>Getting started <i class="icon icon-caret-down"></i></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='/getting-started/templating/'>Templating</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href='/components/'>Components</a></li>
|
||
<li><a href='/cookbook'>Examples</a></li>
|
||
<li>
|
||
<a>Developers <i class="icon icon-caret-down"></i></a>
|
||
<ul>
|
||
<li><a href="/developers/">Setup Development</a></li>
|
||
<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">
|
||
|
||
|
||
<div class='edit-github'><a href='https://github.com/balloob/home-assistant.io/tree/master/source/developers/add_new_platform.markdown'>Edit this page on GitHub</a></div>
|
||
|
||
|
||
|
||
<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 various platform in <a href="https://github.com/balloob/home-assistant/tree/master/homeassistant/components/switch"><code>homeassistant/components/switch/</code></a>. The file <code>\_\_init\_\_.py</code> contains the core logic of all platform and the <code>vendor_name.py</code> files only the relevant platform code.</p>
|
||
|
||
<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/#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>
|
||
|
||
<div class="highlighter-coderay"><div class="CodeRay">
|
||
<div class="code"><pre><span class="keyword">def</span> <span class="function">setup_platform</span>(hass, config, add_devices, discovery_info=<span class="predefined-constant">None</span>)
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
|
||
<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>
|
||
|
||
<div class="highlighter-coderay"><div class="CodeRay">
|
||
<div class="code"><pre><span class="keyword">from</span> <span class="include">homeassistant.loader</span> <span class="keyword">import</span> <span class="include">get_component</span>
|
||
|
||
<span class="keyword">def</span> <span class="function">setup</span>(hass, config):
|
||
discovery = get_component(<span class="string"><span class="delimiter">'</span><span class="content">discovery</span><span class="delimiter">'</span></span>)
|
||
|
||
<span class="keyword">def</span> <span class="function">chromecast_discovered</span>(service, info):
|
||
<span class="docstring"><span class="delimiter">"""</span><span class="content"> Called when a Chromecast has been discovered. </span><span class="delimiter">"""</span></span>
|
||
print(<span class="string"><span class="delimiter">"</span><span class="content">Discovered a new Chromecast: {}</span><span class="delimiter">"</span></span>.format(info))
|
||
|
||
discovery.listen(
|
||
hass, discovery.services.GOOGLE_CAST, chromecast_discovered)
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
|
||
<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">
|
||
<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/balloob/home-assistant'><i class="icon-github"></i></a>
|
||
|
||
<div class="credit">
|
||
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>
|
||
|
||
<!--[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> |