jeena/home-assistant.github.io
1
0
Fork 0
Code Issues Pull requests Projects Packages Wiki Activity Actions

Site updated at 2015-09-01 08:42:54 UTC

Browse source
This commit is contained in:
Paulus Schoutsen 2015-09-01 01:42:54 -07:00
parent 2e727a5332
commit 5a20d28e54
77 changed files with 4485 additions and 1421 deletions
Download patch file Download diff file Expand all files Collapse all files

60
developers/add_new_platform.html
View file

@ -134,12 +134,38 @@
<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>
<p class='note'>
Platform logic should not interface directly with the devices but use a third-party Python 3 library that speaks the actual API.
</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><a name='discovery'></a></p>
<p>In this function, your platform should create the appropriate entities and
register them with the Home Assistant core. Entities are Home Assistant&rsquo;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>
@ -189,32 +215,6 @@ This option is currently limited to built-in components.
</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&rsquo;s
representation of lights, switches, sensors, etc. It is best practice for all
new entities to inherit the
<a href="https://github.com/balloob/home-assistant/blob/master/homeassistant/helpers/entity.py#L18">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. That is
why it is best practice to reference the existing class.</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>
</article>

16
developers/creating_components.html
View file

@ -147,6 +147,22 @@ Home Assistant will use the directory that contains your config file as the dire
</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 a 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. The following parameters are passed in:</p>

1
developers/credits.html
View file

@ -139,6 +139,7 @@
<li><a href="https://github.com/eagleamon">Joseph Piron</a></li>
<li><a href="https://github.com/jd">Julien Danjou</a></li>
<li><a href="https://github.com/kixam">kixam</a></li>
<li><a href="https://github.com/MakeMeASandwich">MakeMeASandwich</a></li>
<li><a href="https://github.com/fingon">Markus Stenberg</a></li>
<li><a href="https://github.com/michaelarnauts">Michael Arnauts</a></li>
<li><a href="https://github.com/miniconfig">miniconfig</a></li>

52
developers/index.html
View file

@ -104,9 +104,57 @@
<hr class="divider">
<p>Home Assistant is build from the ground-up to be easily extensible by other developers using components. It uses <a href="https://www.python.org/">Python 3</a> for the backend and <a href="https://www.polymer-project.org/">Polymer (Webcomponents)</a> for the frontend.</p>
<p>Home Assistant is build from the ground-up to be easily extensible by other developers using
components. It uses <a href="https://www.python.org/">Python 3</a> for the backend and
<a href="https://www.polymer-project.org/">Polymer (Webcomponents)</a> for the frontend.</p>
<p>For further reading, see:</p>
<p>Home Assistant is open-source and MIT licensed. The source can be found here:</p>
<ul>
<li><a href="https://github.com/home-assistant">home-assistant</a> - Python server-backend</li>
<li><a href="https://github.com/home-assistant-js">home-assistant-js</a> - javascript-backend powering the client</li>
<li><a href="https://github.com/home-assistant-polymer">home-assistant-polymer</a> - Polymer UI</li>
</ul>
<h3><a class='title-link' name='starting-development' href='#starting-development'></a> Starting development</h3>
<p>You will need to setup a development environment if you want to start developing a new feature or
component for Home Assistant.</p>
<ol>
<li>Clone the Home Assistant repository:<br>
<code>git clone https://github.com/balloob/home-assistant.git</code></li>
<li>Setup your computer for development:<br>
<code>python3 setup.py develop</code></li>
</ol>
<p>After following these steps, running <code>hass</code> will invoke your local installation.</p>
<h3><a class='title-link' name='submitting-improvements' href='#submitting-improvements'></a> Submitting improvements</h3>
<p>Improvements to Home Assistant should be submitted one feature at a time using Github pull
requests.</p>
<ol>
<li>Go to <a href="https://github.com/balloob/home-assistant">the Home Assistant repository</a>
and click fork in the top right.</li>
<li>Follow steps in the previous section but with your forked repository.</li>
<li>Create a new branch to hold your changes<br>
<code>git checkout -b some-feature</code></li>
<li>Make the changes you want</li>
<li>Commit the changes<br>
<code>git add .</code><br>
<code>git commit -m "Added some-feature"</code></li>
<li>Push your commited changes back to your fork on Github<br>
<code>git push origin HEAD</code></li>
<li>Follow <a href="https://help.github.com/articles/creating-a-pull-request/">these steps</a> to create your
pull request.</li>
</ol>
<h3><a class='title-link' name='further-reading' href='#further-reading'></a> Further reading</h3>
<ul>
<li><a href="/developers/architecture.html">