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

Site updated at 2016-08-22 08:21:42 UTC

Browse source
This commit is contained in:
Travis CI 2016-08-22 08:21:43 +00:00
parent f9d65cbe57
commit 4acb07bf8e
559 changed files with 18878 additions and 21688 deletions
Download patch file Download diff file Expand all files Collapse all files

10
developers/add_new_platform/index.html
View file

@ -91,7 +91,7 @@
<p>Components that interact with devices are called Entity Components. They are structured in core- and platform logic. This allows the same logic to handle a light to be used by different brands.</p>
<p>For example, the built-in <code>switch</code> component consists of various platform in <a href="https://github.com/home-assistant/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>For example, the built-in <code class="highlighter-rouge">switch</code> component consists of various platform in <a href="https://github.com/home-assistant/home-assistant/tree/master/homeassistant/components/switch"><code class="highlighter-rouge">homeassistant/components/switch/</code></a>. The file <code class="highlighter-rouge">__init__.py</code> contains the core logic of all platform and the <code class="highlighter-rouge">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>
@ -110,11 +110,9 @@
<p>Platforms can specify dependencies and requirements the same way as a component does.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>REQUIREMENTS = [<span class="string"><span class="delimiter">'</span><span class="content">some-package==2.0.0</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">some-other-package==2.5.0</span><span class="delimiter">'</span></span>]
DEPENDENCIES = [<span class="string"><span class="delimiter">'</span><span class="content">mqtt</span><span class="delimiter">'</span></span>]
</pre></div>
</div>
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="n">REQUIREMENTS</span> <span class="o">=</span> <span class="p">[</span><span class="s">'some-package==2.0.0'</span><span class="p">,</span> <span class="s">'some-other-package==2.5.0'</span><span class="p">]</span>
<span class="n">DEPENDENCIES</span> <span class="o">=</span> <span class="p">[</span><span class="s">'mqtt'</span><span class="p">]</span>
</code></pre>
</div>

6
developers/architecture/index.html
View file

@ -108,9 +108,9 @@
<ul>
<li>The <strong>Event Bus</strong> facilitates the firing and listening of events. This is the beating heart of Home Assistant.</li>
<li>The <strong>State Machine</strong> keeps track of the states of things. Fires a <code>state_changed</code> event when a state has been changed.</li>
<li>The <strong>Service Registry</strong> listens on the event bus for <code>call_service</code> events and allows other code to register services.</li>
<li>The <strong>Timer</strong> will send a <code>time_changed</code> event every 1 second on the event bus.</li>
<li>The <strong>State Machine</strong> keeps track of the states of things. Fires a <code class="highlighter-rouge">state_changed</code> event when a state has been changed.</li>
<li>The <strong>Service Registry</strong> listens on the event bus for <code class="highlighter-rouge">call_service</code> events and allows other code to register services.</li>
<li>The <strong>Timer</strong> will send a <code class="highlighter-rouge">time_changed</code> event every 1 second on the event bus.</li>
</ul>
<p class="img">

25
developers/architecture_components/index.html
View file

@ -102,7 +102,7 @@ Diagram showing interaction between components and the Home Assistant core.
<p>These components will track devices within a specific domain and consist of a core part and platform-specific logic. These components make their information available via the State Machine and the Event Bus. The component will also register services in the Service Registry to expose control of the devices.</p>
<p>For example, one of the built-in components is the <code>switch</code> component. This component is responsible for interaction with different types of switches.</p>
<p>For example, one of the built-in components is the <code class="highlighter-rouge">switch</code> component. This component is responsible for interaction with different types of switches.</p>
<p>A platform provides support for a particular kind/brand of device. For example, a switch could use a WeMo or Orvibo platform, and a light component might interact with the Hue or LiFX platform.</p>
@ -112,31 +112,22 @@ Diagram showing interaction between components and the Home Assistant core.
<p>These components provide small pieces of home automation logic or services that do common tasks within your house.</p>
<p>For example the <a href="/components/device_sun_light_trigger/"><code>device_sun_light_trigger</code> component</a> tracks the state of devices and the sun to make sure that the lights are turned on when it gets dark and there are people home. The component uses logic along the following lines:</p>
<p>For example the <a href="/components/device_sun_light_trigger/"><code class="highlighter-rouge">device_sun_light_trigger</code> component</a> tracks the state of devices and the sun to make sure that the lights are turned on when it gets dark and there are people home. The component uses logic along the following lines:</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre> In the event that device 'Paulus Nexus 5' changes to the 'Home' state:
<pre><code class="language-plain"> In the event that device 'Paulus Nexus 5' changes to the 'Home' state:
If the sun has set and the lights are not on:
Turn on the lights
</pre></div>
</div>
</div>
</code></pre>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre> In the event that the combined state of all tracked devices changes to 'Not Home':
<pre><code class="language-plain"> In the event that the combined state of all tracked devices changes to 'Not Home':
If the lights are on:
Turn off the lights
</pre></div>
</div>
</div>
</code></pre>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre> In the event of the sun setting:
<pre><code class="language-plain"> In the event of the sun setting:
If the lights are off and the combined state of all tracked device equals 'Home':
Turn on the lights
</pre></div>
</div>
</div>
</code></pre>
<p>An extended example of a home automation component can be found <a href="https://github.com/home-assistant/home-assistant/blob/master/config/custom_components/example.py">here</a>.</p>

16
developers/component_deps_and_reqs/index.html
View file

@ -89,24 +89,20 @@
<hr class="divider">
<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>Home Assistant allows components and platforms to specify their dependencies and requirements using the variables <code class="highlighter-rouge">DEPENDENCIES</code> and <code class="highlighter-rouge">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>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>DEPENDENCIES = [<span class="string"><span class="delimiter">'</span><span class="content">mqtt</span><span class="delimiter">'</span></span>]
</pre></div>
</div>
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="n">DEPENDENCIES</span> <span class="o">=</span> <span class="p">[</span><span class="s">'mqtt'</span><span class="p">]</span>
</code></pre>
</div>
<p>Requirements are Python libraries that you would normally install using <code>pip</code>. If Home Assistant is unable to install the requirements or verify it is installed, the component will fail to load.</p>
<p>Requirements are Python libraries that you would normally install using <code class="highlighter-rouge">pip</code>. If Home Assistant is unable to install the requirements or verify it is installed, the component will fail to load.</p>
<p>Requirements is a list of strings. Each entry is a pip compatible string. For example, the media player Cast platform depends on the Python package PyChromecast v0.6.12:</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>REQUIREMENTS = [<span class="string"><span class="delimiter">'</span><span class="content">pychromecast==0.6.12</span><span class="delimiter">'</span></span>]
</pre></div>
</div>
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="n">REQUIREMENTS</span> <span class="o">=</span> <span class="p">[</span><span class="s">'pychromecast==0.6.12'</span><span class="p">]</span>
</code></pre>
</div>

28
developers/component_discovery/index.html
View file

@ -93,37 +93,35 @@
This option is only available to built-in components.
</p>
<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>
<p>Home Assistant has a discovery service running in the background to discover new devices. Whenever a new device is discovered, an <code class="highlighter-rouge">SERVICE_DISCOVERED</code> event will be fired with the found service and the information. The <code class="highlighter-rouge">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 class="highlighter-rouge">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/home-assistant/netdisco">NetDisco</a>. This library is integrated using <a href="https://github.com/home-assistant/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>Device discovery for Home Assistant has been extracted into an external library called <a href="https://github.com/home-assistant/netdisco">NetDisco</a>. This library is integrated using <a href="https://github.com/home-assistant/home-assistant/blob/dev/homeassistant/components/discovery.py">the <code class="highlighter-rouge">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/home-assistant/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>
<h3><a class="title-link" name="listening-to-service_discovered-events" href="#listening-to-service_discovered-events"></a> Listening to <code class="highlighter-rouge">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>
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="kn">from</span> <span class="nn">homeassistant.loader</span> <span class="kn">import</span> <span class="n">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="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 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 class="keyword">def</span> <span class="function">chromecast_discovered</span>(service, info):
<span class="docstring"><span class="delimiter">&quot;&quot;&quot;</span><span class="content"> Called when a Chromecast has been discovered. </span><span class="delimiter">&quot;&quot;&quot;</span></span>
print(<span class="string"><span class="delimiter">&quot;</span><span class="content">Discovered a new Chromecast: {}</span><span class="delimiter">&quot;</span></span>.format(info))
<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 class="s">""" Called when a Chromecast has been discovered. """</span>
<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>
discovery.listen(
hass, discovery.services.GOOGLE_CAST, chromecast_discovered)
</pre></div>
</div>
<span class="n">discovery</span><span class="o">.</span><span class="n">listen</span><span class="p">(</span>
<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>
</code></pre>
</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/home-assistant/home-assistant/blob/dev/homeassistant/components/discovery.py#L29"><code>SERVICE_HANDLERS</code></a> constant in <a href="https://github.com/home-assistant/home-assistant/blob/dev/homeassistant/components/discovery.py">the <code>discovery</code> component</a>.</p>
<p>The Discovery component is capable of setting up your components before firing the <code class="highlighter-rouge">SERVICE_DISCOVERD</code> event. To do this you will have to update the <a href="https://github.com/home-assistant/home-assistant/blob/dev/homeassistant/components/discovery.py#L29"><code class="highlighter-rouge">SERVICE_HANDLERS</code></a> constant in <a href="https://github.com/home-assistant/home-assistant/blob/dev/homeassistant/components/discovery.py">the <code class="highlighter-rouge">discovery</code> component</a>.</p>
</article>

2
developers/component_events/index.html
View file

@ -89,7 +89,7 @@
<hr class="divider">
<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/home-assistant/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>
<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/home-assistant/home-assistant/blob/dev/homeassistant/helpers/event.py">helper methods</a>. Examples are <code class="highlighter-rouge">track_state_change</code>, <code class="highlighter-rouge">track_point_in_time</code>, <code class="highlighter-rouge">track_time_change</code>.</p>
</article>

86
developers/component_generic_discovery/index.html
View file

@ -89,13 +89,11 @@
<hr class="divider">
<p>New controller or hub components often need to add platforms in sub-components (i.e. Lights &amp; Switches) without additional configuration.<br />
This can be achieved using the <code>homeassistant.components.discovery.load_platform</code> method:</p>
<p>New controller or hub components often need to add platforms in sub-components (i.e. Lights &amp; Switches) without additional configuration.
This can be achieved using the <code class="highlighter-rouge">homeassistant.components.discovery.load_platform</code> method:</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre><span class="keyword">def</span> <span class="function">load_platform</span>(hass, component, platform, info=<span class="predefined-constant">None</span>, hass_config=<span class="predefined-constant">None</span>)
</pre></div>
</div>
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="k">def</span> <span class="nf">load_platform</span><span class="p">(</span><span class="n">hass</span><span class="p">,</span> <span class="n">component</span><span class="p">,</span> <span class="n">platform</span><span class="p">,</span> <span class="n">info</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span> <span class="n">hass_config</span><span class="o">=</span><span class="bp">None</span><span class="p">)</span>
</code></pre>
</div>
<p>From more info on how this works, refer to the <a href="https://github.com/home-assistant/home-assistant/blob/dev/homeassistant/components/discovery.py#L78">load_platform</a> method.</p>
@ -106,71 +104,61 @@ This can be achieved using the <code>homeassistant.components.discovery.load_pla
<p>Configuration required for your new hub component:</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre><span class="key">myflashyhub</span>:
<span class="key">example</span>: <span class="string"><span class="content">setting</span></span>
</pre></div>
</div>
<div class="language-yaml highlighter-rouge"><pre class="highlight"><code><span class="s">myflashyhub</span><span class="pi">:</span>
<span class="s">example</span><span class="pi">:</span> <span class="s">setting</span>
</code></pre>
</div>
<p>The source for your component can be located in your configuration directory for now:</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>~/.homeassistant/custom_components/myflashyhub.py
<div class="language-bash highlighter-rouge"><pre class="highlight"><code>~/.homeassistant/custom_components/myflashyhub.py
~/.homeassistant/custom_components/light/myflashyhub.py
~/.homeassistant/custom_components/switch/myflashyhub.py
</pre></div>
</div>
</code></pre>
</div>
<p>In the hub component <code>myflashyhub.py</code> you can call your light and switch components. To pass any non-serializable information to the platforms in the sub-component, you can use a global variable.</p>
<p>In the hub component <code class="highlighter-rouge">myflashyhub.py</code> you can call your light and switch components. To pass any non-serializable information to the platforms in the sub-component, you can use a global variable.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre><span class="keyword">from</span> <span class="include">homeassistant.components.discovery</span> <span class="keyword">import</span> <span class="include">load_platform</span>
DOMAIN = <span class="string"><span class="delimiter">'</span><span class="content">myflashyhub</span><span class="delimiter">'</span></span>
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="kn">from</span> <span class="nn">homeassistant.components.discovery</span> <span class="kn">import</span> <span class="n">load_platform</span>
<span class="n">DOMAIN</span> <span class="o">=</span> <span class="s">'myflashyhub'</span>
MFH_GLOBAL = <span class="predefined-constant">None</span>
<span class="n">MFH_GLOBAL</span> <span class="o">=</span> <span class="bp">None</span>
<span class="keyword">def</span> <span class="function">setup</span>(hass, config):
<span class="docstring"><span class="delimiter">&quot;&quot;&quot;</span><span class="content">Your controller/hub specific code.</span><span class="delimiter">&quot;&quot;&quot;</span></span>
<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 class="s">"""Your controller/hub specific code."""</span>
<span class="keyword">global</span> MFH_GLOBAL
<span class="keyword">if</span> MFH_GLOBAL <span class="keyword">is</span> <span class="predefined-constant">None</span>:
MFH_GLOBAL = SomeObjectToInitialiseGlobal
<span class="comment">#--- snip ---</span>
load_platform(hass, <span class="string"><span class="delimiter">'</span><span class="content">light</span><span class="delimiter">'</span></span>, DOMAIN)
load_platform(hass, <span class="string"><span class="delimiter">'</span><span class="content">switch</span><span class="delimiter">'</span></span>, DOMAIN, {<span class="string"><span class="delimiter">'</span><span class="content">optional</span><span class="delimiter">'</span></span>: <span class="string"><span class="delimiter">'</span><span class="content">arguments</span><span class="delimiter">'</span></span>})
</pre></div>
</div>
<span class="k">global</span> <span class="n">MFH_GLOBAL</span>
<span class="k">if</span> <span class="n">MFH_GLOBAL</span> <span class="ow">is</span> <span class="bp">None</span><span class="p">:</span>
<span class="n">MFH_GLOBAL</span> <span class="o">=</span> <span class="n">SomeObjectToInitialiseGlobal</span>
<span class="c">#--- snip ---</span>
<span class="n">load_platform</span><span class="p">(</span><span class="n">hass</span><span class="p">,</span> <span class="s">'light'</span><span class="p">,</span> <span class="n">DOMAIN</span><span class="p">)</span>
<span class="n">load_platform</span><span class="p">(</span><span class="n">hass</span><span class="p">,</span> <span class="s">'switch'</span><span class="p">,</span> <span class="n">DOMAIN</span><span class="p">,</span> <span class="p">{</span><span class="s">'optional'</span><span class="p">:</span> <span class="s">'arguments'</span><span class="p">})</span>
</code></pre>
</div>
<p>Add your custom device specific code to the <code>setup_platform</code> method in <code>light/myflashyhub.py</code> and <code>switch/myflashyhub</code>.</p>
<p>Add your custom device specific code to the <code class="highlighter-rouge">setup_platform</code> method in <code class="highlighter-rouge">light/myflashyhub.py</code> and <code class="highlighter-rouge">switch/myflashyhub</code>.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre><span class="keyword">import</span> <span class="include">homeassistant.components.myflashyhub</span> <span class="keyword">as</span> myflashyhub
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="kn">import</span> <span class="nn">homeassistant.components.myflashyhub</span> <span class="kn">as</span> <span class="nn">myflashyhub</span>
<span class="comment"># 'switch' will receive discovery_info={'optional': 'arguments'} </span>
<span class="comment"># as passed in above. 'light' will receive discovery_info=None</span>
<span class="keyword">def</span> <span class="function">setup_platform</span>(hass, config, add_devices, discovery_info=<span class="predefined-constant">None</span>):
<span class="docstring"><span class="delimiter">&quot;&quot;&quot;</span><span class="content">Your switch/light specific code.</span><span class="delimiter">&quot;&quot;&quot;</span></span>
<span class="comment"># You can now use myflashyhub.MFH_GLOBAL</span>
</pre></div>
</div>
<span class="c"># 'switch' will receive discovery_info={'optional': 'arguments'} </span>
<span class="c"># as passed in above. 'light' will receive discovery_info=None</span>
<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 class="s">"""Your switch/light specific code."""</span>
<span class="c"># You can now use myflashyhub.MFH_GLOBAL</span>
</code></pre>
</div>
<p>The <code>load_platform</code> method allows the platforms to be loaded with the need for any additional platform entries in your <code>configuration.yaml</code> file, which normally would have been:</p>
<p>The <code class="highlighter-rouge">load_platform</code> method allows the platforms to be loaded with the need for any additional platform entries in your <code class="highlighter-rouge">configuration.yaml</code> file, which normally would have been:</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre><span class="comment">#light:</span>
<span class="comment"># platform: myflashyhub</span>
<span class="comment">#switch:</span>
<span class="comment"># platform: myflashyhub</span>
</pre></div>
</div>
<div class="language-yaml highlighter-rouge"><pre class="highlight"><code><span class="c1">#light:</span>
<span class="c1"># platform: myflashyhub</span>
<span class="c1">#switch:</span>
<span class="c1"># platform: myflashyhub</span>
</code></pre>
</div>
<p class="note ">
In the past, this was achieved by adding your component to the <code>DISCOVERY_PLATFORMS</code> in the target sub-component. Generic discovery through <code>load_platform()</code> allows you to load any sub-component, including custom components, without changing the sub-component.
In the past, this was achieved by adding your component to the <code class="highlighter-rouge">DISCOVERY_PLATFORMS</code> in the target sub-component. Generic discovery through <code class="highlighter-rouge">load_platform()</code> allows you to load any sub-component, including custom components, without changing the sub-component.
</p>

22
developers/component_initialization/index.html
View file

@ -89,7 +89,7 @@
<hr class="divider">
<p>After loading, the bootstrapper will call <code>setup(hass, config)</code> method on the component to initialize it.</p>
<p>After loading, the bootstrapper will call <code class="highlighter-rouge">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> hass: the Home Assistant instance</h3>
@ -104,19 +104,19 @@
</thead>
<tbody>
<tr>
<td><code>hass.config</code></td>
<td><code class="highlighter-rouge">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/home-assistant/home-assistant/blob/dev/homeassistant/core.py#L687">Details</a></td>
</tr>
<tr>
<td><code>hass.states</code></td>
<td><code class="highlighter-rouge">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/home-assistant/home-assistant/blob/dev/homeassistant/core.py#L434">See available methods</a>.</td>
</tr>
<tr>
<td><code>hass.bus</code></td>
<td><code class="highlighter-rouge">hass.bus</code></td>
<td>This is the EventBus. It allows you to trigger and listen for events.<br /><a href="https://github.com/home-assistant/home-assistant/blob/dev/homeassistant/core.py#L229">See available methods</a>.</td>
</tr>
<tr>
<td><code>hass.services</code></td>
<td><code class="highlighter-rouge">hass.services</code></td>
<td>This is the ServiceRegistry. It allows you to register services.<br /><a href="https://github.com/home-assistant/home-assistant/blob/dev/homeassistant/core.py#L568">See available methods</a>.</td>
</tr>
</tbody>
@ -124,18 +124,16 @@
<h3><a class="title-link" name="config-user-given-configuration" href="#config-user-given-configuration"></a> config: User given configuration.</h3>
<p>The <code>config</code> parameter 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>The <code class="highlighter-rouge">config</code> parameter 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 class="language-yaml highlighter-rouge"><pre class="highlight"><code><span class="s">example</span><span class="pi">:</span>
<span class="s">host</span><span class="pi">:</span> <span class="s">paulusschoutsen.nl</span>
</code></pre>
</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>
<p>Then in the setup method of your component you will be able to refer to <code class="highlighter-rouge">config['example']['host']</code> to get the value <code class="highlighter-rouge">paulusschoutsen.nl</code>.</p>
</article>

6
developers/component_loading/index.html
View file

@ -89,11 +89,11 @@
<hr class="divider">
<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>
<p>A component will be loaded on start if a section (ie. <code class="highlighter-rouge">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>&lt;config directory&gt;/custom_components/&lt;component name&gt;</code></li>
<li><code>homeassistant/components/&lt;component name&gt;</code> (built-in components)</li>
<li><code class="highlighter-rouge">&lt;config directory&gt;/custom_components/&lt;component name&gt;</code></li>
<li><code class="highlighter-rouge">homeassistant/components/&lt;component name&gt;</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>

8
developers/component_states/index.html
View file

@ -94,10 +94,10 @@
<p>A state can have several attributes that will help the frontend in displaying your state:</p>
<ul>
<li><code>friendly_name</code>: this name will be used as the name of the device</li>
<li><code>entity_picture</code>: this picture will be shown instead of the domain icon</li>
<li><code>unit_of_measurement</code>: this will be appended to the state in the interface</li>
<li><code>hidden</code>: This is a suggestion to the frontend on if the state should be hidden</li>
<li><code class="highlighter-rouge">friendly_name</code>: this name will be used as the name of the device</li>
<li><code class="highlighter-rouge">entity_picture</code>: this picture will be shown instead of the domain icon</li>
<li><code class="highlighter-rouge">unit_of_measurement</code>: this will be appended to the state in the interface</li>
<li><code class="highlighter-rouge">hidden</code>: This is a suggestion to the frontend on if the state should be hidden</li>
</ul>
<p>These attributes are defined in <a href="https://github.com/home-assistant/home-assistant/blob/master/homeassistant/helpers/entity.py#L180">homeassistant.helpers.entity</a>.</p>

10
developers/component_visibility/index.html
View file

@ -89,13 +89,11 @@
<hr class="divider">
<p>Generally, when creating a new entity for Home Assistant you will want it to be a class that inherits the <a href="https://github.com/home-assistant/home-assistant/blob/master/homeassistant/helpers/entity.py">homeassistant.helpers.entity.Entity</a> class. If this is done, visibility will be handled for you. <br />
You can set a suggestion for your entity’s visibility by setting the <code>hidden</code> property by doing something similar to the following.</p>
<p>Generally, when creating a new entity for Home Assistant you will want it to be a class that inherits the <a href="https://github.com/home-assistant/home-assistant/blob/master/homeassistant/helpers/entity.py">homeassistant.helpers.entity.Entity</a> class. If this is done, visibility will be handled for you.
You can set a suggestion for your entity’s visibility by setting the <code class="highlighter-rouge">hidden</code> property by doing something similar to the following.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre><span class="predefined-constant">self</span>.hidden = <span class="predefined-constant">True</span>
</pre></div>
</div>
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="bp">self</span><span class="o">.</span><span class="n">hidden</span> <span class="o">=</span> <span class="bp">True</span>
</code></pre>
</div>
<p>This will SUGGEST that the active frontend hides the entity. This requires that the active frontend support hidden cards (the default frontend does) and that the value of hidden be included in your attributes dictionary (see above). The Entity abstract class will take care of this for you.</p>

14
developers/creating_components/index.html
View file

@ -93,17 +93,15 @@
<h3><a class="title-link" name="example-component" href="#example-component"></a> Example component</h3>
<p>Add <code>hello_state:</code> to your <code>configuration.yaml</code> file and create a file <code>&lt;config_dir&gt;/custom_components/hello_state.py</code> with the below code to test it locally.</p>
<p>Add <code class="highlighter-rouge">hello_state:</code> to your <code class="highlighter-rouge">configuration.yaml</code> file and create a file <code class="highlighter-rouge">&lt;config_dir&gt;/custom_components/hello_state.py</code> with the below code to test it locally.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>DOMAIN = <span class="string"><span class="delimiter">'</span><span class="content">hello_state</span><span class="delimiter">'</span></span>
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="n">DOMAIN</span> <span class="o">=</span> <span class="s">'hello_state'</span>
<span class="keyword">def</span> <span class="function">setup</span>(hass, config):
hass.states.set(<span class="string"><span class="delimiter">'</span><span class="content">hello.world</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">Paulus</span><span class="delimiter">'</span></span>)
<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 class="n">hass</span><span class="o">.</span><span class="n">states</span><span class="o">.</span><span class="nb">set</span><span class="p">(</span><span class="s">'hello.world'</span><span class="p">,</span> <span class="s">'Paulus'</span><span class="p">)</span>
<span class="keyword">return</span> <span class="predefined-constant">True</span>
</pre></div>
</div>
<span class="k">return</span> <span class="bp">True</span>
</code></pre>
</div>
<p>For more examples, see the <a href="/cookbook/#custom-python-component-examples">Custom Python Component Examples</a> on our examples page.</p>

30
developers/development_catching_up/index.html
View file

@ -89,35 +89,31 @@
<hr class="divider">
<p>If you’re taking a while developing your feature and would like to catch up with what’s in the current Home Assistant <code>dev</code> branch, you can use <code>git rebase</code> to do so. This will pull the latest Home Assistant changes locally, rewind your commits, bring in the latest changes from Home Assistant and then replay all of your commits on top.</p>
<p>If you’re taking a while developing your feature and would like to catch up with what’s in the current Home Assistant <code class="highlighter-rouge">dev</code> branch, you can use <code class="highlighter-rouge">git rebase</code> to do so. This will pull the latest Home Assistant changes locally, rewind your commits, bring in the latest changes from Home Assistant and then replay all of your commits on top.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre># Run this from your feature branch
$ git fetch upstream dev # to pull the latest changes into a local dev branch
$ git rebase upstream/dev # to put those changes into your feature branch before your changes
</pre></div>
</div>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="c"># Run this from your feature branch</span>
<span class="gp">$ </span>git fetch upstream dev <span class="c"># to pull the latest changes into a local dev branch</span>
<span class="gp">$ </span>git rebase upstream/dev <span class="c"># to put those changes into your feature branch before your changes</span>
</code></pre>
</div>
<p>If rebase detects conflicts, you can repeat the following process until all changes have been resolved:</p>
<ol>
<li><code>git status</code> will show you the file with the conflict.</li>
<li>Edit the file and resolving the lines between <code>&lt;&lt;&lt;&lt; | &gt;&gt;&gt;&gt;</code></li>
<li>Add the modified file <code>git add &lt;file&gt;</code> or <code>git add .</code></li>
<li>Continue rebase <code>git rebase --continue</code></li>
<li><code class="highlighter-rouge">git status</code> will show you the file with the conflict.</li>
<li>Edit the file and resolving the lines between <code class="highlighter-rouge">&lt;&lt;&lt;&lt; | &gt;&gt;&gt;&gt;</code></li>
<li>Add the modified file <code class="highlighter-rouge">git add &lt;file&gt;</code> or <code class="highlighter-rouge">git add .</code></li>
<li>Continue rebase <code class="highlighter-rouge">git rebase --continue</code></li>
<li>Repeat until you’ve resolved all conflicts.</li>
</ol>
<p>There is other workflows that is covered in detail in the <a href="https://help.github.com/articles/fork-a-repo/">Github documentation</a>. Add an additional <code>remote</code> after you clone your fork.</p>
<p>There is other workflows that is covered in detail in the <a href="https://help.github.com/articles/fork-a-repo/">Github documentation</a>. Add an additional <code class="highlighter-rouge">remote</code> after you clone your fork.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>$ git remote add upstream https://github.com/home-assistant/home-assistant.git
</pre></div>
</div>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>git remote add upstream https://github.com/home-assistant/home-assistant.git
</code></pre>
</div>
<p>and then simply <code>git pull --rebase upstream dev</code>.</p>
<p>and then simply <code class="highlighter-rouge">git pull --rebase upstream dev</code>.</p>

8
developers/development_checklist/index.html
View file

@ -92,10 +92,10 @@
<p>After you finish your work:</p>
<ul>
<li>Check that all dependencies are included via the <code>REQUIREMENTS</code> variable in your platform/component and only imported inside functions that use them.</li>
<li>Add any new dependencies to <code>requirements_all.txt</code> if needed. Use <code>script/gen_requirements_all.py</code>.</li>
<li>Update the <code>.coveragerc</code> file to exclude your platform if there are no tests available or your new code uses a 3rd party library for communication with the device/service/sensor.</li>
<li>Provide some documentation for <a href="https://home-assistant.io/">home-assistant.io</a>. It’s OK to just add a docstring with configuration details (sample entry for <code>configuration.yaml</code> file and alike) to the file header as a start. Visit the <a href="/developers/website/">website documentation</a> for further information on contributing to <a href="https://github.com/home-assistant/home-assistant.io">home-assistant.io</a>.</li>
<li>Check that all dependencies are included via the <code class="highlighter-rouge">REQUIREMENTS</code> variable in your platform/component and only imported inside functions that use them.</li>
<li>Add any new dependencies to <code class="highlighter-rouge">requirements_all.txt</code> if needed. Use <code class="highlighter-rouge">script/gen_requirements_all.py</code>.</li>
<li>Update the <code class="highlighter-rouge">.coveragerc</code> file to exclude your platform if there are no tests available or your new code uses a 3rd party library for communication with the device/service/sensor.</li>
<li>Provide some documentation for <a href="https://home-assistant.io/">home-assistant.io</a>. It’s OK to just add a docstring with configuration details (sample entry for <code class="highlighter-rouge">configuration.yaml</code> file and alike) to the file header as a start. Visit the <a href="/developers/website/">website documentation</a> for further information on contributing to <a href="https://github.com/home-assistant/home-assistant.io">home-assistant.io</a>.</li>
</ul>

20
developers/development_environment/index.html
View file

@ -89,22 +89,20 @@
<hr class="divider">
<p>You will need to set up a development environment if you want to start developing a new feature or component for Home Assistant. Please follow these steps to get setup.<br />
<p>You will need to set up a development environment if you want to start developing a new feature or component for Home Assistant. Please follow these steps to get setup.
Visit the <a href="https://github.com/home-assistant/home-assistant">the Home Assistant repository</a> first and click fork in the top right.</p>
<p>We suggest that you setup a virtual environment using <a href="https://docs.python.org/3.4/library/venv.html"><code>venv</code></a> before running the setup script.</p>
<p>We suggest that you setup a virtual environment using <a href="https://docs.python.org/3.4/library/venv.html"><code class="highlighter-rouge">venv</code></a> before running the setup script.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>$ git clone https://github.com/YOUR_GIT_USERNAME/home-assistant.git
$ cd home-assistant
$ git remote add upstream https://github.com/home-assistant/home-assistant.git
$ script/setup
</pre></div>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>git clone https://github.com/YOUR_GIT_USERNAME/home-assistant.git
<span class="gp">$ </span><span class="nb">cd </span>home-assistant
<span class="gp">$ </span>git remote add upstream https://github.com/home-assistant/home-assistant.git
<span class="gp">$ </span>script/setup
</code></pre>
</div>
</div>
<p>On Windows you can use <code>python setup.py develop</code> instead of the setup script.</p>
<p>On Windows you can use <code class="highlighter-rouge">python setup.py develop</code> instead of the setup script.</p>
<p>After following these steps, running <code>hass</code> will invoke your local installation.</p>
<p>After following these steps, running <code class="highlighter-rouge">hass</code> will invoke your local installation.</p>

14
developers/development_submitting/index.html
View file

@ -92,16 +92,16 @@
<p>Improvements, fixes, and new features to Home Assistant should be submitted one feature at a time using GitHub <a href="https://help.github.com/articles/using-pull-requests">Pull Requests</a>.</p>
<ol>
<li>From your fork, create a new branch to hold your changes<br />
<code>git checkout -b some-feature</code></li>
<li>From your fork, create a new branch to hold your changes
<code class="highlighter-rouge">git checkout -b some-feature</code></li>
<li>Make the changes you want, create a <a href="/developers/add_new_platform/">new platform</a>, develop a <a href="/developers/creating_components/">new component</a>, or fix <a href="https://github.com/home-assistant/home-assistant/issues">issues</a>.</li>
<li><a href="/developers/development_testing/">Test your changes</a> and check for style violations</li>
<li>Commit the changes if all <a href="/developers/development_checklist/">musts</a> are covered.<br />
<code>git add .</code><br />
<code>git commit -m "Added some-feature"</code></li>
<li>Commit the changes if all <a href="/developers/development_checklist/">musts</a> are covered.
<code class="highlighter-rouge">git add .</code>
<code class="highlighter-rouge">git commit -m "Added some-feature"</code></li>
<li>Consider to add tests to ensure that the code works.</li>
<li>Push your committed changes back to your fork on GitHub<br />
<code>git push origin HEAD</code></li>
<li>Push your committed changes back to your fork on GitHub
<code class="highlighter-rouge">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>
<li>Check for comments and suggestions on your Pull Request and keep an eye on the <a href="https://travis-ci.org/home-assistant/home-assistant/">CI output</a>.</li>
</ol>

42
developers/development_testing/index.html
View file

@ -93,56 +93,48 @@
<h3><a class="title-link" name="local-testing" href="#local-testing"></a> Local testing</h3>
<p>It’s highly recommanded to run <code>tox</code> before you create your Pull Request to avoid annoying fixes. Local testing requires <code>tox</code> to be installed.</p>
<p>It’s highly recommanded to run <code class="highlighter-rouge">tox</code> before you create your Pull Request to avoid annoying fixes. Local testing requires <code class="highlighter-rouge">tox</code> to be installed.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>$ pip3 install tox
</pre></div>
</div>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>pip3 install tox
</code></pre>
</div>
<p>Start the test of your code with <code>tox</code>.</p>
<p>Start the test of your code with <code class="highlighter-rouge">tox</code>.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>$ tox
</pre></div>
</div>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>tox
</code></pre>
</div>
<p>This will run unit tests against python 3.4 and 3.5 (if both are available locally), as well as run a set of tests which validate <code>pep8</code> and <code>pylint</code> style of the code.</p>
<p>This will run unit tests against python 3.4 and 3.5 (if both are available locally), as well as run a set of tests which validate <code class="highlighter-rouge">pep8</code> and <code class="highlighter-rouge">pylint</code> style of the code.</p>
<h4><a class="title-link" name="testing-tips" href="#testing-tips"></a> Testing Tips</h4>
<p>You can optionally run tests on only one tox target using the <code>-e</code> option to select an environment. For instance <code>tox -e lint</code> will run the linters only, <code>tox -e py34</code> will run unit tests only on python 3.4.</p>
<p>You can optionally run tests on only one tox target using the <code class="highlighter-rouge">-e</code> option to select an environment. For instance <code class="highlighter-rouge">tox -e lint</code> will run the linters only, <code class="highlighter-rouge">tox -e py34</code> will run unit tests only on python 3.4.</p>
<p>Tox uses virtual environments under the hood to create isolated testing environments. The Tox virtual environments will get out date when requirements change causing test errors. Run <code>tox -r</code> to create new Tox virtual environments.</p>
<p>Tox uses virtual environments under the hood to create isolated testing environments. The Tox virtual environments will get out date when requirements change causing test errors. Run <code class="highlighter-rouge">tox -r</code> to create new Tox virtual environments.</p>
<p>During development on a specific file, it can speed up your workflow to just run tests and linting related to the file that you’re working on. To run individual files:</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>$ flake8 homeassistant/core.py
$ pylint homeassistant/core.py
$ py.test tests/test_core.py
</pre></div>
</div>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>flake8 homeassistant/core.py
<span class="gp">$ </span>pylint homeassistant/core.py
<span class="gp">$ </span>py.test tests/test_core.py
</code></pre>
</div>
<h3><a class="title-link" name="prevent-linter-errors" href="#prevent-linter-errors"></a> Prevent Linter Errors</h3>
<p>You can save yourself the hassle of extra commits just to fix style errors by enabling the flake8 git commit hook. It will check your code when you attempt to commit to the repository. It will block the commit if there are any style issues, giving you a chance to fix it.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>$ pip3 install flake8 flake8-docstrings
$ flake8 --install-hook=git
</pre></div>
</div>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>pip3 install flake8 flake8-docstrings
<span class="gp">$ </span>flake8 --install-hook<span class="o">=</span>git
</code></pre>
</div>
<p>The flake8-docstrings extension will check docstrings according to <a href="https://www.python.org/dev/peps/pep-0257/">PEP257</a> when running flake8.</p>
<h3><a class="title-link" name="notes-on-pylint-and-pep8-validation" href="#notes-on-pylint-and-pep8-validation"></a> Notes on PyLint and PEP8 validation</h3>
<p>In case a PyLint warning cannot be avoided, add a comment to disable the PyLint check for that line. This can be done using the format <code># pylint: disable=YOUR-ERROR-NAME</code>. Example of an unavoidable PyLint warning is if you do not use the passed in datetime if you’re listening for time change.</p>
<p>In case a PyLint warning cannot be avoided, add a comment to disable the PyLint check for that line. This can be done using the format <code class="highlighter-rouge"># pylint: disable=YOUR-ERROR-NAME</code>. Example of an unavoidable PyLint warning is if you do not use the passed in datetime if you’re listening for time change.</p>

76
developers/development_validation/index.html
View file

@ -89,28 +89,28 @@
<hr class="divider">
<p>The <code>configuration.yaml</code> file contains the configuration options for components and platforms. To ensure that the given configuration provided by the user is valid we use <a href="https://pypi.python.org/pypi/voluptuous">voluptuous</a> to check it. Certain entries are optional or could be required for the setup of a platform or a component. Others must be of a definied type or out of an already defined list.</p>
<p>The <code class="highlighter-rouge">configuration.yaml</code> file contains the configuration options for components and platforms. To ensure that the given configuration provided by the user is valid we use <a href="https://pypi.python.org/pypi/voluptuous">voluptuous</a> to check it. Certain entries are optional or could be required for the setup of a platform or a component. Others must be of a definied type or out of an already defined list.</p>
<p>The goal of testing the configuration is to assure that users have a great experience due to notifications if something is wrong with a platform or component setup before Home Assistant is running.</p>
<p>Beside the <a href="https://pypi.python.org/pypi/voluptuous">voluptuous</a> default types are a bunch of custom types available. To get a full overview take a look at the <a href="https://github.com/home-assistant/home-assistant/blob/master/homeassistant/helpers/config_validation.py">config_validation.py</a> helper.</p>
<ul>
<li>Types: <code>string</code>, <code>byte</code>, and <code>boolean</code></li>
<li>Entity ID: <code>entity_id</code> and <code>entity_ids</code></li>
<li>Numbers: <code>small_float</code> and <code>positive_int</code></li>
<li>Time: <code>time</code>, <code>time_zone</code></li>
<li>Misc: <code>template</code>, <code>slug</code>, <code>temperature_unit</code>, <code>latitude</code>, <code>longitude</code>, <code>isfile</code>, <code>sun_event</code>, <code>ensure_list</code>, and <code>icon</code></li>
<li>Types: <code class="highlighter-rouge">string</code>, <code class="highlighter-rouge">byte</code>, and <code class="highlighter-rouge">boolean</code></li>
<li>Entity ID: <code class="highlighter-rouge">entity_id</code> and <code class="highlighter-rouge">entity_ids</code></li>
<li>Numbers: <code class="highlighter-rouge">small_float</code> and <code class="highlighter-rouge">positive_int</code></li>
<li>Time: <code class="highlighter-rouge">time</code>, <code class="highlighter-rouge">time_zone</code></li>
<li>Misc: <code class="highlighter-rouge">template</code>, <code class="highlighter-rouge">slug</code>, <code class="highlighter-rouge">temperature_unit</code>, <code class="highlighter-rouge">latitude</code>, <code class="highlighter-rouge">longitude</code>, <code class="highlighter-rouge">isfile</code>, <code class="highlighter-rouge">sun_event</code>, <code class="highlighter-rouge">ensure_list</code>, and <code class="highlighter-rouge">icon</code></li>
</ul>
<p>To validate plaforms using <a href="/components/mqtt/">MQTT</a> there are <code>valid_subscribe_topic</code> and <code>valid_publish_topic</code> present.</p>
<p>To validate plaforms using <a href="/components/mqtt/">MQTT</a> there are <code class="highlighter-rouge">valid_subscribe_topic</code> and <code class="highlighter-rouge">valid_publish_topic</code> present.</p>
<p>Some things to keep in mind:</p>
<ul>
<li>Use the constants which are definded in <code>const.py</code>.</li>
<li>Import <code>PLATFORM_SCHEMA</code> from parent component and extend it.</li>
<li>Preferred order is <code>required</code> first, then <code>optional</code>.</li>
<li>Use the constants which are definded in <code class="highlighter-rouge">const.py</code>.</li>
<li>Import <code class="highlighter-rouge">PLATFORM_SCHEMA</code> from parent component and extend it.</li>
<li>Preferred order is <code class="highlighter-rouge">required</code> first, then <code class="highlighter-rouge">optional</code>.</li>
</ul>
<h3><a class="title-link" name="snippets" href="#snippets"></a> Snippets</h3>
@ -121,60 +121,52 @@
<p>It’s common to set a default for a sensor if the user is not providing a name to use.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>DEFAULT_NAME = <span class="string"><span class="delimiter">'</span><span class="content">Sensor name</span><span class="delimiter">'</span></span>
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="n">DEFAULT_NAME</span> <span class="o">=</span> <span class="s">'Sensor name'</span>
PLATFORM_SCHEMA = PLATFORM_SCHEMA.extend({
...
vol.Optional(CONF_NAME, default=DEFAULT_NAME): cv.string,
</pre></div>
</div>
<span class="n">PLATFORM_SCHEMA</span> <span class="o">=</span> <span class="n">PLATFORM_SCHEMA</span><span class="o">.</span><span class="n">extend</span><span class="p">({</span>
<span class="o">...</span>
<span class="n">vol</span><span class="o">.</span><span class="n">Optional</span><span class="p">(</span><span class="n">CONF_NAME</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="n">DEFAULT_NAME</span><span class="p">):</span> <span class="n">cv</span><span class="o">.</span><span class="n">string</span><span class="p">,</span>
</code></pre>
</div>
<h3><a class="title-link" name="limit-the-values" href="#limit-the-values"></a> Limit the values</h3>
<p>In certain cases you want to limit the user’s input to a couple of options.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>DEFAULT_METHOD = <span class="string"><span class="delimiter">'</span><span class="content">GET</span><span class="delimiter">'</span></span>
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="n">DEFAULT_METHOD</span> <span class="o">=</span> <span class="s">'GET'</span>
PLATFORM_SCHEMA = PLATFORM_SCHEMA.extend({
...
vol.Optional(CONF_METHOD, default=DEFAULT_METHOD): vol.In([<span class="string"><span class="delimiter">'</span><span class="content">POST</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">GET</span><span class="delimiter">'</span></span>]),
</pre></div>
</div>
<span class="n">PLATFORM_SCHEMA</span> <span class="o">=</span> <span class="n">PLATFORM_SCHEMA</span><span class="o">.</span><span class="n">extend</span><span class="p">({</span>
<span class="o">...</span>
<span class="n">vol</span><span class="o">.</span><span class="n">Optional</span><span class="p">(</span><span class="n">CONF_METHOD</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="n">DEFAULT_METHOD</span><span class="p">):</span> <span class="n">vol</span><span class="o">.</span><span class="n">In</span><span class="p">([</span><span class="s">'POST'</span><span class="p">,</span> <span class="s">'GET'</span><span class="p">]),</span>
</code></pre>
</div>
<h3><a class="title-link" name="port" href="#port"></a> Port</h3>
<p>As all port numbers are coming out of the range 1 till 65535.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>DEFAULT_PORT = <span class="integer">993</span>
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="n">DEFAULT_PORT</span> <span class="o">=</span> <span class="mi">993</span>
PLATFORM_SCHEMA = PLATFORM_SCHEMA.extend({
...
vol.Optional(CONF_PORT, default=DEFAULT_PORT): cv.port,
</pre></div>
</div>
<span class="n">PLATFORM_SCHEMA</span> <span class="o">=</span> <span class="n">PLATFORM_SCHEMA</span><span class="o">.</span><span class="n">extend</span><span class="p">({</span>
<span class="o">...</span>
<span class="n">vol</span><span class="o">.</span><span class="n">Optional</span><span class="p">(</span><span class="n">CONF_PORT</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="n">DEFAULT_PORT</span><span class="p">):</span> <span class="n">cv</span><span class="o">.</span><span class="n">port</span><span class="p">,</span>
</code></pre>
</div>
<h3><a class="title-link" name="lists" href="#lists"></a> Lists</h3>
<p>If a sensor has a pre-defined list of available options it should be tested if the configuration entry matches it.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>SENSOR_TYPES = {
<span class="string"><span class="delimiter">'</span><span class="content">article_cache</span><span class="delimiter">'</span></span>: (<span class="string"><span class="delimiter">'</span><span class="content">Article Cache</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">MB</span><span class="delimiter">'</span></span>),
<span class="string"><span class="delimiter">'</span><span class="content">average_download_rate</span><span class="delimiter">'</span></span>: (<span class="string"><span class="delimiter">'</span><span class="content">Average Speed</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">MB/s</span><span class="delimiter">'</span></span>),
}
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="n">SENSOR_TYPES</span> <span class="o">=</span> <span class="p">{</span>
<span class="s">'article_cache'</span><span class="p">:</span> <span class="p">(</span><span class="s">'Article Cache'</span><span class="p">,</span> <span class="s">'MB'</span><span class="p">),</span>
<span class="s">'average_download_rate'</span><span class="p">:</span> <span class="p">(</span><span class="s">'Average Speed'</span><span class="p">,</span> <span class="s">'MB/s'</span><span class="p">),</span>
<span class="p">}</span>
PLATFORM_SCHEMA = PLATFORM_SCHEMA.extend({
...
vol.Optional(CONF_MONITORED_VARIABLES, default=[]):
vol.All(ensure_list, [vol.In(SENSOR_TYPES)]),
</pre></div>
</div>
<span class="n">PLATFORM_SCHEMA</span> <span class="o">=</span> <span class="n">PLATFORM_SCHEMA</span><span class="o">.</span><span class="n">extend</span><span class="p">({</span>
<span class="o">...</span>
<span class="n">vol</span><span class="o">.</span><span class="n">Optional</span><span class="p">(</span><span class="n">CONF_MONITORED_VARIABLES</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="p">[]):</span>
<span class="n">vol</span><span class="o">.</span><span class="n">All</span><span class="p">(</span><span class="n">ensure_list</span><span class="p">,</span> <span class="p">[</span><span class="n">vol</span><span class="o">.</span><span class="n">In</span><span class="p">(</span><span class="n">SENSOR_TYPES</span><span class="p">)]),</span>
</code></pre>
</div>

42
developers/frontend/index.html
View file

@ -92,9 +92,9 @@
<p>Home Assistant uses <a href="https://www.polymer-project.org/">Polymer</a> for the UI and <a href="http://optimizely.github.io/nuclear-js/">NuclearJS</a> for maintaing the app state.</p>
<ul>
<li>Polymer allows building encapsulated custom HTML elements.<br />
<li>Polymer allows building encapsulated custom HTML elements.
<a href="https://github.com/home-assistant/home-assistant-polymer">Home-Assistant-Polymer source code on GitHub.</a></li>
<li>NuclearJS is a reactive flux built with ImmutableJS data structures.<br />
<li>NuclearJS is a reactive flux built with ImmutableJS data structures.
<a href="https://github.com/home-assistant/home-assistant-js">Home-Assistant-JS source code on GitHub.</a></li>
</ul>
@ -104,47 +104,41 @@ Do not use development mode in production. Home Assistant uses aggressive cachin
<h2><a class="title-link" name="setting-up-the-environment" href="#setting-up-the-environment"></a> Setting up the environment</h2>
<p>Home Assistant will by default serve the compiled version of the frontend. To enable development mode for Home Assistant, update your <code>configuration.yaml</code> to have these lines:</p>
<p>Home Assistant will by default serve the compiled version of the frontend. To enable development mode for Home Assistant, update your <code class="highlighter-rouge">configuration.yaml</code> to have these lines:</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre><span class="key">http</span>:
<span class="key">development</span>: <span class="string"><span class="content">1</span></span>
</pre></div>
</div>
<div class="language-yaml highlighter-rouge"><pre class="highlight"><code><span class="s">http</span><span class="pi">:</span>
<span class="s">development</span><span class="pi">:</span> <span class="s">1</span>
</code></pre>
</div>
<p>As everything is compiled into the file <code>frontend.html</code> you do not want to work with the compiled version but with the seperate files during development.</p>
<p>As everything is compiled into the file <code class="highlighter-rouge">frontend.html</code> you do not want to work with the compiled version but with the seperate files during development.</p>
<p>Next step is to get the frontend code. When you clone the Home Assistant repository, the frontend repository is not cloned by default. You can setup the frontend development environment by running:</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>$ script/setup
</pre></div>
</div>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>script/setup
</code></pre>
</div>
<h2><a class="title-link" name="development" href="#development"></a> Development</h2>
<p>While you are developing, you need to have Rollup running to have your JavaScript changes be made available.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>$ cd homeassistant/components/frontend/www_static/home-assistant-polymer
$ npm run js_dev
</pre></div>
</div>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span><span class="nb">cd </span>homeassistant/components/frontend/www_static/home-assistant-polymer
<span class="gp">$ </span>npm run js_dev
</code></pre>
</div>
<p>The source code for the frontend can be found in three different directories:</p>
<ul>
<li>UI: <code>homeassistant/components/frontend/www_static/home-assistant-polymer/src/</code></li>
<li>Core: <code>homeassistant/components/frontend/www_static/home-assistant-polymer/home-assistant-js/src/</code></li>
<li>Panels: <code>homeassistant/components/frontend/www_static/home-assistant-polymer/panels/</code></li>
<li>UI: <code class="highlighter-rouge">homeassistant/components/frontend/www_static/home-assistant-polymer/src/</code></li>
<li>Core: <code class="highlighter-rouge">homeassistant/components/frontend/www_static/home-assistant-polymer/home-assistant-js/src/</code></li>
<li>Panels: <code class="highlighter-rouge">homeassistant/components/frontend/www_static/home-assistant-polymer/panels/</code></li>
</ul>
<h1><a class="title-link" name="building-the-polymer-frontend" href="#building-the-polymer-frontend"></a> Building the Polymer frontend</h1>
<p>Building a new version of the frontend is as simple as running <code>script/build_frontend</code>. This fires off the following commands:</p>
<p>Building a new version of the frontend is as simple as running <code class="highlighter-rouge">script/build_frontend</code>. This fires off the following commands:</p>
<ul>
<li><strong>home-assistant-polymer</strong>: Install NPM dependencies.</li>
@ -155,8 +149,8 @@ $ npm run js_dev
<li>Vulcanize and minify the core and panel sources to build dir.</li>
</ul>
</li>
<li>Copy the webcomponents polyfill <code>webcomponents-lite.min.js</code> from <strong>home-assistant-polymer</strong> to <code>components/frontend/www_static/webcomponents-lite.min.js</code>.</li>
<li>Copy the final frontend build <code>frontend.html</code> and panel sources from <strong>home-assistant-polymer</strong> to <code>components/frontend/www_static/frontend/</code>.</li>
<li>Copy the webcomponents polyfill <code class="highlighter-rouge">webcomponents-lite.min.js</code> from <strong>home-assistant-polymer</strong> to <code class="highlighter-rouge">components/frontend/www_static/webcomponents-lite.min.js</code>.</li>
<li>Copy the final frontend build <code class="highlighter-rouge">frontend.html</code> and panel sources from <strong>home-assistant-polymer</strong> to <code class="highlighter-rouge">components/frontend/www_static/frontend/</code>.</li>
<li>Generate MD5 hashes of core and panel sources.</li>
<li>Create gzip versions of all the sources.</li>
</ul>

10
developers/frontend_add_card/index.html
View file

@ -99,14 +99,14 @@
<p><img src="/images/frontend/frontend-badges.png" alt="Badges in the frontend" /></p>
<p>The different badges are located in the file <a href="https://github.com/home-assistant/home-assistant-polymer/blob/master/src/components/entity/ha-state-label-badge.html"><code>/src/components/entity/ha-state-label-badge.html</code></a>.</p>
<p>The different badges are located in the file <a href="https://github.com/home-assistant/home-assistant-polymer/blob/master/src/components/entity/ha-state-label-badge.html"><code class="highlighter-rouge">/src/components/entity/ha-state-label-badge.html</code></a>.</p>
<p>Adding a custom card type can be done with a few simple steps. For this example we will add a new state card for the domain <code>camera</code>:</p>
<p>Adding a custom card type can be done with a few simple steps. For this example we will add a new state card for the domain <code class="highlighter-rouge">camera</code>:</p>
<ol>
<li>Add <code>'camera'</code> to the array <code>DOMAINS_WITH_CARD</code> in the file <a href="https://github.com/home-assistant/home-assistant-polymer/blob/master/src/util/hass-util.html#L11">/util/hass-util.html</a>.</li>
<li>Create the files <code>state-card-camera.html</code> in the folder <a href="https://github.com/home-assistant/home-assistant-polymer/tree/master/src/state-summary">/state-summary/</a>.</li>
<li>Add <code>&lt;link rel="import" href="state-card-camera.html"&gt;</code> to <a href="https://github.com/home-assistant/home-assistant-polymer/blob/master/src/state-summary/state-card-content.html">state-card-content.html</a>.</li>
<li>Add <code class="highlighter-rouge">'camera'</code> to the array <code class="highlighter-rouge">DOMAINS_WITH_CARD</code> in the file <a href="https://github.com/home-assistant/home-assistant-polymer/blob/master/src/util/hass-util.html#L11">/util/hass-util.html</a>.</li>
<li>Create the files <code class="highlighter-rouge">state-card-camera.html</code> in the folder <a href="https://github.com/home-assistant/home-assistant-polymer/tree/master/src/state-summary">/state-summary/</a>.</li>
<li>Add <code class="highlighter-rouge">&lt;link rel="import" href="state-card-camera.html"&gt;</code> to <a href="https://github.com/home-assistant/home-assistant-polymer/blob/master/src/state-summary/state-card-content.html">state-card-content.html</a>.</li>
</ol>

8
developers/frontend_add_more_info/index.html
View file

@ -96,12 +96,12 @@
The more info dialog for a light allows the user to control the color and the brightness.
</p>
<p>The instructions to add a more info dialog are very similar to adding a new card type. This example will add a new more info component for the domain <code>camera</code>:</p>
<p>The instructions to add a more info dialog are very similar to adding a new card type. This example will add a new more info component for the domain <code class="highlighter-rouge">camera</code>:</p>
<ol>
<li>Add <code>'camera'</code> to the array <code>DOMAINS_WITH_MORE_INFO</code> in the file <a href="https://github.com/home-assistant/home-assistant-polymer/blob/master/src/util/hass-util.html#L24">util/hass-util.html</a>.</li>
<li>Create the files <code>more-info-camera.html</code> in the folder <a href="https://github.com/home-assistant/home-assistant-polymer/tree/master/src/more-infos">/more-infos</a>.</li>
<li>Add <code>&lt;link rel="import" href="more-info-camera.html"&gt;</code> to <a href="https://github.com/home-assistant/home-assistant-polymer/blob/master/src/more-infos/more-info-content.html">more-info-content.html</a></li>
<li>Add <code class="highlighter-rouge">'camera'</code> to the array <code class="highlighter-rouge">DOMAINS_WITH_MORE_INFO</code> in the file <a href="https://github.com/home-assistant/home-assistant-polymer/blob/master/src/util/hass-util.html#L24">util/hass-util.html</a>.</li>
<li>Create the files <code class="highlighter-rouge">more-info-camera.html</code> in the folder <a href="https://github.com/home-assistant/home-assistant-polymer/tree/master/src/more-infos">/more-infos</a>.</li>
<li>Add <code class="highlighter-rouge">&lt;link rel="import" href="more-info-camera.html"&gt;</code> to <a href="https://github.com/home-assistant/home-assistant-polymer/blob/master/src/more-infos/more-info-content.html">more-info-content.html</a></li>
</ol>

114
developers/frontend_creating_custom_panels/index.html
View file

@ -91,71 +91,67 @@
<p>Any component has the possibility to add a panel to the frontend. Panels will be rendered full screen and have real-time access to the Home Assistant object via JavaScript. Examples of this in the app are map, logbook and history.</p>
<p>Create a file called <code>hello.html</code> in your <config dir="">/panels/.</config></p>
<p>Create a file called <code class="highlighter-rouge">hello.html</code> in your <config dir="">/panels/.</config></p>
<p>The <code>hello.html</code> contains the needed building blocks to create the elements inside the view.</p>
<p>The <code class="highlighter-rouge">hello.html</code> contains the needed building blocks to create the elements inside the view.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>&lt;dom-module id=<span class="string"><span class="delimiter">'</span><span class="content">ha-panel-hello</span><span class="delimiter">'</span></span>&gt;
<span class="tag">&lt;template&gt;</span>
<span class="tag">&lt;style&gt;</span>
<span class="inline"> <span class="tag">p</span> {
<span class="key">font-weight</span>: <span class="value">bold</span>;
}</span>
<span class="tag">&lt;/style&gt;</span>
<span class="tag">&lt;p&gt;</span>Hello {{who}}. Greetings from Home Assistant.<span class="tag">&lt;/p&gt;</span>
<span class="tag">&lt;/template&gt;</span>
&lt;<span class="regexp"><span class="delimiter">/</span><span class="content">dom-module&gt;
<div class="language-javascript highlighter-rouge"><pre class="highlight"><code><span class="o">&lt;</span><span class="nx">dom</span><span class="o">-</span><span class="nx">module</span> <span class="nx">id</span><span class="o">=</span><span class="s1">'ha-panel-hello'</span><span class="o">&gt;</span>
<span class="o">&lt;</span><span class="nx">template</span><span class="o">&gt;</span>
<span class="o">&lt;</span><span class="nx">style</span><span class="o">&gt;</span>
<span class="nx">p</span> <span class="p">{</span>
<span class="nx">font</span><span class="o">-</span><span class="nx">weight</span><span class="err">:</span> <span class="nx">bold</span><span class="p">;</span>
<span class="p">}</span>
<span class="o">&lt;</span><span class="sr">/style</span><span class="err">&gt;
</span> <span class="o">&lt;</span><span class="nx">p</span><span class="o">&gt;</span><span class="nx">Hello</span> <span class="p">{{</span><span class="nx">who</span><span class="p">}}.</span> <span class="nx">Greetings</span> <span class="nx">from</span> <span class="nx">Home</span> <span class="nx">Assistant</span><span class="p">.</span><span class="o">&lt;</span><span class="sr">/p</span><span class="err">&gt;
</span> <span class="o">&lt;</span><span class="sr">/template</span><span class="err">&gt;
</span><span class="o">&lt;</span><span class="sr">/dom-module</span><span class="err">&gt;
</span>
<span class="o">&lt;</span><span class="sr">/script</span><span class="err">&gt;
</span><span class="nx">Polymer</span><span class="p">({</span>
<span class="na">is</span><span class="p">:</span> <span class="s1">'ha-panel-hello'</span><span class="p">,</span>
<span class="na">properties</span><span class="p">:</span> <span class="p">{</span>
<span class="c1">// Home Assistant object</span>
<span class="na">hass</span><span class="p">:</span> <span class="p">{</span>
<span class="na">type</span><span class="p">:</span> <span class="nb">Object</span><span class="p">,</span>
<span class="p">},</span>
<span class="c1">// If should render in narrow mode</span>
<span class="na">narrow</span><span class="p">:</span> <span class="p">{</span>
<span class="na">type</span><span class="p">:</span> <span class="nb">Boolean</span><span class="p">,</span>
<span class="na">value</span><span class="p">:</span> <span class="kc">false</span><span class="p">,</span>
<span class="p">},</span>
<span class="c1">// If sidebar is currently shown</span>
<span class="na">showMenu</span><span class="p">:</span> <span class="p">{</span>
<span class="na">type</span><span class="p">:</span> <span class="nb">Boolean</span><span class="p">,</span>
<span class="na">value</span><span class="p">:</span> <span class="kc">false</span><span class="p">,</span>
<span class="p">},</span>
<span class="c1">// Home Assistant panel info</span>
<span class="c1">// panel.config contains config passed to register_panel serverside</span>
<span class="na">panel</span><span class="p">:</span> <span class="p">{</span>
<span class="na">type</span><span class="p">:</span> <span class="nb">Object</span><span class="p">,</span>
<span class="p">},</span>
<span class="na">who</span><span class="p">:</span> <span class="p">{</span>
<span class="na">type</span><span class="p">:</span> <span class="nb">String</span><span class="p">,</span>
<span class="na">computed</span><span class="p">:</span> <span class="s1">'computeWho(panel)'</span><span class="p">,</span>
<span class="p">}</span>
<span class="p">},</span>
&lt;</span><span class="delimiter">/</span></span>script&gt;
Polymer({
<span class="key">is</span>: <span class="string"><span class="delimiter">'</span><span class="content">ha-panel-hello</span><span class="delimiter">'</span></span>,
<span class="key">properties</span>: {
<span class="comment">// Home Assistant object</span>
<span class="key">hass</span>: {
<span class="key">type</span>: Object,
},
<span class="comment">// If should render in narrow mode</span>
<span class="key">narrow</span>: {
<span class="key">type</span>: Boolean,
<span class="key">value</span>: <span class="predefined-constant">false</span>,
},
<span class="comment">// If sidebar is currently shown</span>
<span class="key">showMenu</span>: {
<span class="key">type</span>: Boolean,
<span class="key">value</span>: <span class="predefined-constant">false</span>,
},
<span class="comment">// Home Assistant panel info</span>
<span class="comment">// panel.config contains config passed to register_panel serverside</span>
<span class="key">panel</span>: {
<span class="key">type</span>: Object,
},
<span class="key">who</span>: {
<span class="key">type</span>: String,
<span class="key">computed</span>: <span class="string"><span class="delimiter">'</span><span class="content">computeWho(panel)</span><span class="delimiter">'</span></span>,
}
},
<span class="function">computeWho</span>: <span class="keyword">function</span> (panel) {
<span class="keyword">return</span> panel &amp;&amp; panel.config &amp;&amp; panel.config.who ? panel.config.who : <span class="string"><span class="delimiter">'</span><span class="content">World</span><span class="delimiter">'</span></span>;
},
});
&lt;<span class="regexp"><span class="delimiter">/</span><span class="content">script&gt;
</span></span></pre></div>
</div>
<span class="na">computeWho</span><span class="p">:</span> <span class="kd">function</span> <span class="p">(</span><span class="nx">panel</span><span class="p">)</span> <span class="p">{</span>
<span class="k">return</span> <span class="nx">panel</span> <span class="o">&amp;&amp;</span> <span class="nx">panel</span><span class="p">.</span><span class="nx">config</span> <span class="o">&amp;&amp;</span> <span class="nx">panel</span><span class="p">.</span><span class="nx">config</span><span class="p">.</span><span class="nx">who</span> <span class="p">?</span> <span class="nx">panel</span><span class="p">.</span><span class="nx">config</span><span class="p">.</span><span class="nx">who</span> <span class="p">:</span> <span class="s1">'World'</span><span class="p">;</span>
<span class="p">},</span>
<span class="p">});</span>
<span class="o">&lt;</span><span class="sr">/script</span><span class="err">&gt;
</span></code></pre>
</div>
<p>Create an entry for the new panel in your <code>configuration.yaml</code> file:</p>
<p>Create an entry for the new panel in your <code class="highlighter-rouge">configuration.yaml</code> file:</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre><span class="key">panel_custom</span>:
- <span class="string"><span class="content">name: hello_world</span></span>
<span class="key">sidebar_title</span>: <span class="string"><span class="content">Hello World</span></span>
<span class="key">sidebar_icon</span>: <span class="string"><span class="content">mdi:hand-pointing-right</span></span>
<span class="key">url_path</span>: <span class="string"><span class="content">hello_world</span></span>
<span class="key">webcomponent_path</span>: <span class="string"><span class="content">&lt;config dir&gt;/panels/hello.html</span></span>
</pre></div>
</div>
<div class="language-yaml highlighter-rouge"><pre class="highlight"><code><span class="s">panel_custom</span><span class="pi">:</span>
<span class="pi">-</span> <span class="s">name</span><span class="pi">:</span> <span class="s">hello_world</span>
<span class="s">sidebar_title</span><span class="pi">:</span> <span class="s">Hello World</span>
<span class="s">sidebar_icon</span><span class="pi">:</span> <span class="s">mdi:hand-pointing-right</span>
<span class="s">url_path</span><span class="pi">:</span> <span class="s">hello_world</span>
<span class="s">webcomponent_path</span><span class="pi">:</span> <span class="s">&lt;config dir&gt;/panels/hello.html</span>
</code></pre>
</div>
<p>For more examples, see the <a href="/cookbook#custom-panel-examples">Custom panel Examples</a> on our examples page.</p>

28
developers/multiple_instances/index.html
View file

@ -89,7 +89,7 @@
<hr class="divider">
<p>Home Assistant supports running multiple synchronized instances using a master-slave model. Whenever <code>events.fire</code> or <code>states.set</code> is called on the slave it will forward it to the master. The master will replicate all events and changed states to its slaves.</p>
<p>Home Assistant supports running multiple synchronized instances using a master-slave model. Whenever <code class="highlighter-rouge">events.fire</code> or <code class="highlighter-rouge">states.set</code> is called on the slave it will forward it to the master. The master will replicate all events and changed states to its slaves.</p>
<p class="img">
<a href="/images/architecture/architecture-remote.png">
@ -100,24 +100,22 @@
<p>A slave instance can be started with the following code and has the same support for components as a master instance.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre><span class="keyword">import</span> <span class="include">homeassistant.remote</span> <span class="keyword">as</span> remote
<span class="keyword">import</span> <span class="include">homeassistant.bootstrap</span> <span class="keyword">as</span> bootstrap
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="kn">import</span> <span class="nn">homeassistant.remote</span> <span class="kn">as</span> <span class="nn">remote</span>
<span class="kn">import</span> <span class="nn">homeassistant.bootstrap</span> <span class="kn">as</span> <span class="nn">bootstrap</span>
<span class="comment"># Location of the Master API: host, password, port.</span>
<span class="comment"># Password and port are optional.</span>
remote_api = remote.API(<span class="string"><span class="delimiter">&quot;</span><span class="content">127.0.0.1</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">password</span><span class="delimiter">&quot;</span></span>, <span class="integer">8124</span>)
<span class="c"># Location of the Master API: host, password, port.</span>
<span class="c"># Password and port are optional.</span>
<span class="n">remote_api</span> <span class="o">=</span> <span class="n">remote</span><span class="o">.</span><span class="n">API</span><span class="p">(</span><span class="s">"127.0.0.1"</span><span class="p">,</span> <span class="s">"password"</span><span class="p">,</span> <span class="mi">8124</span><span class="p">)</span>
<span class="comment"># Initialize slave</span>
hass = remote.HomeAssistant(remote_api)
<span class="c"># Initialize slave</span>
<span class="n">hass</span> <span class="o">=</span> <span class="n">remote</span><span class="o">.</span><span class="n">HomeAssistant</span><span class="p">(</span><span class="n">remote_api</span><span class="p">)</span>
<span class="comment"># To add an interface to the slave on localhost:8123</span>
bootstrap.setup_component(hass, <span class="string"><span class="delimiter">'</span><span class="content">frontend</span><span class="delimiter">'</span></span>)
<span class="c"># To add an interface to the slave on localhost:8123</span>
<span class="n">bootstrap</span><span class="o">.</span><span class="n">setup_component</span><span class="p">(</span><span class="n">hass</span><span class="p">,</span> <span class="s">'frontend'</span><span class="p">)</span>
hass.start()
hass.block_till_stopped()
</pre></div>
</div>
<span class="n">hass</span><span class="o">.</span><span class="n">start</span><span class="p">()</span>
<span class="n">hass</span><span class="o">.</span><span class="n">block_till_stopped</span><span class="p">()</span>
</code></pre>
</div>
<p class="note">

150
developers/platform_example_light/index.html
View file

@ -91,108 +91,104 @@
<p>This example is for adding support for the imaginary Awesome Lights. It shows the different best practices for developing a platform.</p>
<p>Similar to Example Sensor Platform, Copy the code below and create it as a file in <code>&lt;config_dir&gt;/custom_components/light/awesomelights.py</code>.</p>
<p>Similar to Example Sensor Platform, Copy the code below and create it as a file in <code class="highlighter-rouge">&lt;config_dir&gt;/custom_components/light/awesomelights.py</code>.</p>
<p>Add the following to your configuration.yaml:</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre><span class="key">light</span>:
- <span class="string"><span class="content">platform: awesomelights</span></span>
<span class="key">host</span>: <span class="string"><span class="content">HOST_HERE</span></span>
<span class="key">username</span>: <span class="string"><span class="content">USERNAME_HERE</span></span>
<span class="key">password</span>: <span class="string"><span class="content">PASSWORD_HERE_OR_secrets.yaml</span></span>
</pre></div>
</div>
<div class="language-yaml highlighter-rouge"><pre class="highlight"><code><span class="s">light</span><span class="pi">:</span>
<span class="pi">-</span> <span class="s">platform</span><span class="pi">:</span> <span class="s">awesomelights</span>
<span class="s">host</span><span class="pi">:</span> <span class="s">HOST_HERE</span>
<span class="s">username</span><span class="pi">:</span> <span class="s">USERNAME_HERE</span>
<span class="s">password</span><span class="pi">:</span> <span class="s">PASSWORD_HERE_OR_secrets.yaml</span>
</code></pre>
</div>
<p>Note the <code>platform</code> name matches the filename for the source code.</p>
<p>Note the <code class="highlighter-rouge">platform</code> name matches the filename for the source code.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre><span class="keyword">import</span> <span class="include">logging</span>
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="kn">import</span> <span class="nn">logging</span>
<span class="comment"># Import the device class from the component that you want to support</span>
<span class="keyword">from</span> <span class="include">homeassistant.components.light</span> <span class="keyword">import</span> <span class="include">ATTR_BRIGHTNESS</span>, <span class="include">Light</span>
<span class="keyword">from</span> <span class="include">homeassistant.const</span> <span class="keyword">import</span> <span class="include">CONF_HOST</span>, <span class="include">CONF_USERNAME</span>, <span class="include">CONF_PASSWORD</span>
<span class="c"># Import the device class from the component that you want to support</span>
<span class="kn">from</span> <span class="nn">homeassistant.components.light</span> <span class="kn">import</span> <span class="n">ATTR_BRIGHTNESS</span><span class="p">,</span> <span class="n">Light</span>
<span class="kn">from</span> <span class="nn">homeassistant.const</span> <span class="kn">import</span> <span class="n">CONF_HOST</span><span class="p">,</span> <span class="n">CONF_USERNAME</span><span class="p">,</span> <span class="n">CONF_PASSWORD</span>
<span class="comment"># Home Assistant depends on 3rd party packages for API specific code.</span>
REQUIREMENTS = [<span class="string"><span class="delimiter">'</span><span class="content">awesome_lights==1.2.3</span><span class="delimiter">'</span></span>]
<span class="c"># Home Assistant depends on 3rd party packages for API specific code.</span>
<span class="n">REQUIREMENTS</span> <span class="o">=</span> <span class="p">[</span><span class="s">'awesome_lights==1.2.3'</span><span class="p">]</span>
_LOGGER = logging.getLogger(__name__)
<span class="n">_LOGGER</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">(</span><span class="n">__name__</span><span class="p">)</span>
<span class="keyword">def</span> <span class="function">setup_platform</span>(hass, config, add_devices, discovery_info=<span class="predefined-constant">None</span>):
<span class="docstring"><span class="delimiter">&quot;&quot;&quot;</span><span class="content">Setup the Awesome Light platform.</span><span class="delimiter">&quot;&quot;&quot;</span></span>
<span class="keyword">import</span> <span class="include">awesomelights</span>
<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 class="s">"""Setup the Awesome Light platform."""</span>
<span class="kn">import</span> <span class="nn">awesomelights</span>
<span class="comment"># Validate passed in config</span>
host = config.get(CONF_HOST)
username = config.get(CONF_USERNAME)
password = config.get(CONF_PASSWORD)
<span class="c"># Validate passed in config</span>
<span class="n">host</span> <span class="o">=</span> <span class="n">config</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">CONF_HOST</span><span class="p">)</span>
<span class="n">username</span> <span class="o">=</span> <span class="n">config</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">CONF_USERNAME</span><span class="p">)</span>
<span class="n">password</span> <span class="o">=</span> <span class="n">config</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">CONF_PASSWORD</span><span class="p">)</span>
<span class="keyword">if</span> host <span class="keyword">is</span> <span class="predefined-constant">None</span> <span class="keyword">or</span> username <span class="keyword">is</span> <span class="predefined-constant">None</span> <span class="keyword">or</span> password <span class="keyword">is</span> <span class="predefined-constant">None</span>:
_LOGGER.error(<span class="string"><span class="delimiter">'</span><span class="content">Invalid config. Expected %s, %s and %s</span><span class="delimiter">'</span></span>,
CONF_HOST, CONF_USERNAME, CONF_PASSWORD)
<span class="keyword">return</span> <span class="predefined-constant">False</span>
<span class="k">if</span> <span class="n">host</span> <span class="ow">is</span> <span class="bp">None</span> <span class="ow">or</span> <span class="n">username</span> <span class="ow">is</span> <span class="bp">None</span> <span class="ow">or</span> <span class="n">password</span> <span class="ow">is</span> <span class="bp">None</span><span class="p">:</span>
<span class="n">_LOGGER</span><span class="o">.</span><span class="n">error</span><span class="p">(</span><span class="s">'Invalid config. Expected </span><span class="si">%</span><span class="s">s, </span><span class="si">%</span><span class="s">s and </span><span class="si">%</span><span class="s">s'</span><span class="p">,</span>
<span class="n">CONF_HOST</span><span class="p">,</span> <span class="n">CONF_USERNAME</span><span class="p">,</span> <span class="n">CONF_PASSWORD</span><span class="p">)</span>
<span class="k">return</span> <span class="bp">False</span>
<span class="comment"># Setup connection with devices/cloud</span>
hub = awesomelights.Hub(host, username, password)
<span class="c"># Setup connection with devices/cloud</span>
<span class="n">hub</span> <span class="o">=</span> <span class="n">awesomelights</span><span class="o">.</span><span class="n">Hub</span><span class="p">(</span><span class="n">host</span><span class="p">,</span> <span class="n">username</span><span class="p">,</span> <span class="n">password</span><span class="p">)</span>
<span class="comment"># Verify that passed in config works</span>
<span class="keyword">if</span> <span class="keyword">not</span> hub.is_valid_login():
_LOGGER.error(<span class="string"><span class="delimiter">'</span><span class="content">Could not connect to AwesomeLight hub</span><span class="delimiter">'</span></span>)
<span class="keyword">return</span> <span class="predefined-constant">False</span>
<span class="c"># Verify that passed in config works</span>
<span class="k">if</span> <span class="ow">not</span> <span class="n">hub</span><span class="o">.</span><span class="n">is_valid_login</span><span class="p">():</span>
<span class="n">_LOGGER</span><span class="o">.</span><span class="n">error</span><span class="p">(</span><span class="s">'Could not connect to AwesomeLight hub'</span><span class="p">)</span>
<span class="k">return</span> <span class="bp">False</span>
<span class="comment"># Add devices</span>
add_devices(AwesomeLight(light) <span class="keyword">for</span> light <span class="keyword">in</span> hub.lights())
<span class="c"># Add devices</span>
<span class="n">add_devices</span><span class="p">(</span><span class="n">AwesomeLight</span><span class="p">(</span><span class="n">light</span><span class="p">)</span> <span class="k">for</span> <span class="n">light</span> <span class="ow">in</span> <span class="n">hub</span><span class="o">.</span><span class="n">lights</span><span class="p">())</span>
<span class="keyword">class</span> <span class="class">AwesomeLight</span>(Light):
<span class="docstring"><span class="delimiter">&quot;&quot;&quot;</span><span class="content">Representation of an Awesome Light.</span><span class="delimiter">&quot;&quot;&quot;</span></span>
<span class="k">class</span> <span class="nc">AwesomeLight</span><span class="p">(</span><span class="n">Light</span><span class="p">):</span>
<span class="s">"""Representation of an Awesome Light."""</span>
<span class="keyword">def</span> <span class="function">__init__</span>(<span class="predefined-constant">self</span>, light):
<span class="docstring"><span class="delimiter">&quot;&quot;&quot;</span><span class="content">Initialize an AwesomeLight.</span><span class="delimiter">&quot;&quot;&quot;</span></span>
<span class="predefined-constant">self</span>._light = light
<span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">light</span><span class="p">):</span>
<span class="s">"""Initialize an AwesomeLight."""</span>
<span class="bp">self</span><span class="o">.</span><span class="n">_light</span> <span class="o">=</span> <span class="n">light</span>
<span class="decorator">@property</span>
<span class="keyword">def</span> <span class="function">name</span>(<span class="predefined-constant">self</span>):
<span class="docstring"><span class="delimiter">&quot;&quot;&quot;</span><span class="content">Return the display name of this light.</span><span class="delimiter">&quot;&quot;&quot;</span></span>
<span class="keyword">return</span> <span class="predefined-constant">self</span>._light.name
<span class="nd">@property</span>
<span class="k">def</span> <span class="nf">name</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="s">"""Return the display name of this light."""</span>
<span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_light</span><span class="o">.</span><span class="n">name</span>
<span class="decorator">@property</span>
<span class="keyword">def</span> <span class="function">brightness</span>(<span class="predefined-constant">self</span>):
<span class="docstring"><span class="delimiter">&quot;&quot;&quot;</span><span class="content">Brightness of the light (an integer in the range 1-255).</span><span class="content">
</span><span class="content">
</span><span class="content"> This method is optional. Removing it indicates to Home Assistant</span><span class="content">
</span><span class="content"> that brightness is not supported for this light.</span><span class="content">
</span><span class="content"> </span><span class="delimiter">&quot;&quot;&quot;</span></span>
<span class="keyword">return</span> <span class="predefined-constant">self</span>._light.brightness
<span class="nd">@property</span>
<span class="k">def</span> <span class="nf">brightness</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="s">"""Brightness of the light (an integer in the range 1-255).
<span class="decorator">@property</span>
<span class="keyword">def</span> <span class="function">is_on</span>(<span class="predefined-constant">self</span>):
<span class="docstring"><span class="delimiter">&quot;&quot;&quot;</span><span class="content">Return true if light is on.</span><span class="delimiter">&quot;&quot;&quot;</span></span>
<span class="keyword">return</span> <span class="predefined-constant">self</span>._light.is_on()
This method is optional. Removing it indicates to Home Assistant
that brightness is not supported for this light.
"""</span>
<span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_light</span><span class="o">.</span><span class="n">brightness</span>
<span class="keyword">def</span> <span class="function">turn_on</span>(<span class="predefined-constant">self</span>, **kwargs):
<span class="docstring"><span class="delimiter">&quot;&quot;&quot;</span><span class="content">Instruct the light to turn on.</span><span class="content">
</span><span class="content">
</span><span class="content"> You can skip the brightness part if your light does not support</span><span class="content">
</span><span class="content"> brightness control.</span><span class="content">
</span><span class="content"> </span><span class="delimiter">&quot;&quot;&quot;</span></span>
<span class="predefined-constant">self</span>._light.brightness = kwargs.get(ATTR_BRIGHTNESS, <span class="integer">255</span>)
<span class="predefined-constant">self</span>._light.turn_on()
<span class="nd">@property</span>
<span class="k">def</span> <span class="nf">is_on</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="s">"""Return true if light is on."""</span>
<span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_light</span><span class="o">.</span><span class="n">is_on</span><span class="p">()</span>
<span class="keyword">def</span> <span class="function">turn_off</span>(<span class="predefined-constant">self</span>, **kwargs):
<span class="docstring"><span class="delimiter">&quot;&quot;&quot;</span><span class="content">Instruct the light to turn off.</span><span class="delimiter">&quot;&quot;&quot;</span></span>
<span class="predefined-constant">self</span>._light.turn_off()
<span class="k">def</span> <span class="nf">turn_on</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
<span class="s">"""Instruct the light to turn on.
<span class="keyword">def</span> <span class="function">update</span>(<span class="predefined-constant">self</span>):
<span class="docstring"><span class="delimiter">&quot;&quot;&quot;</span><span class="content">Fetch new state data for this light.</span><span class="content">
</span><span class="content">
</span><span class="content"> This is the only method that should fetch new data for Home Assistant.</span><span class="content">
</span><span class="content"> </span><span class="delimiter">&quot;&quot;&quot;</span></span>
<span class="predefined-constant">self</span>._light.update()
</pre></div>
</div>
You can skip the brightness part if your light does not support
brightness control.
"""</span>
<span class="bp">self</span><span class="o">.</span><span class="n">_light</span><span class="o">.</span><span class="n">brightness</span> <span class="o">=</span> <span class="n">kwargs</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">ATTR_BRIGHTNESS</span><span class="p">,</span> <span class="mi">255</span><span class="p">)</span>
<span class="bp">self</span><span class="o">.</span><span class="n">_light</span><span class="o">.</span><span class="n">turn_on</span><span class="p">()</span>
<span class="k">def</span> <span class="nf">turn_off</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
<span class="s">"""Instruct the light to turn off."""</span>
<span class="bp">self</span><span class="o">.</span><span class="n">_light</span><span class="o">.</span><span class="n">turn_off</span><span class="p">()</span>
<span class="k">def</span> <span class="nf">update</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="s">"""Fetch new state data for this light.
This is the only method that should fetch new data for Home Assistant.
"""</span>
<span class="bp">self</span><span class="o">.</span><span class="n">_light</span><span class="o">.</span><span class="n">update</span><span class="p">()</span>
</code></pre>
</div>

54
developers/platform_example_sensor/index.html
View file

@ -93,49 +93,45 @@
<h3><a class="title-link" name="installation" href="#installation"></a> Installation</h3>
<p>Copy the code below and create it as a file in <code>&lt;config_dir&gt;/custom_components/sensor/example.py</code>.</p>
<p>Copy the code below and create it as a file in <code class="highlighter-rouge">&lt;config_dir&gt;/custom_components/sensor/example.py</code>.</p>
<p>Add the following to your configuration.yaml:</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre><span class="comment"># Example configuration.yaml entry</span>
<span class="key">sensor</span>:
<span class="key">platform</span>: <span class="string"><span class="content">example</span></span>
</pre></div>
</div>
<div class="language-yaml highlighter-rouge"><pre class="highlight"><code><span class="c1"># Example configuration.yaml entry</span>
<span class="s">sensor</span><span class="pi">:</span>
<span class="s">platform</span><span class="pi">:</span> <span class="s">example</span>
</code></pre>
</div>
<h3><a class="title-link" name="code" href="#code"></a> Code</h3>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre><span class="keyword">from</span> <span class="include">homeassistant.const</span> <span class="keyword">import</span> <span class="include">TEMP_CELSIUS</span>
<span class="keyword">from</span> <span class="include">homeassistant.helpers.entity</span> <span class="keyword">import</span> <span class="include">Entity</span>
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="kn">from</span> <span class="nn">homeassistant.const</span> <span class="kn">import</span> <span class="n">TEMP_CELSIUS</span>
<span class="kn">from</span> <span class="nn">homeassistant.helpers.entity</span> <span class="kn">import</span> <span class="n">Entity</span>
<span class="keyword">def</span> <span class="function">setup_platform</span>(hass, config, add_devices, discovery_info=<span class="predefined-constant">None</span>):
<span class="docstring"><span class="delimiter">&quot;&quot;&quot;</span><span class="content">Setup the sensor platform.</span><span class="delimiter">&quot;&quot;&quot;</span></span>
add_devices([ExampleSensor()])
<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 class="s">"""Setup the sensor platform."""</span>
<span class="n">add_devices</span><span class="p">([</span><span class="n">ExampleSensor</span><span class="p">()])</span>
<span class="keyword">class</span> <span class="class">ExampleSensor</span>(Entity):
<span class="docstring"><span class="delimiter">&quot;&quot;&quot;</span><span class="content">Representation of a Sensor.</span><span class="delimiter">&quot;&quot;&quot;</span></span>
<span class="k">class</span> <span class="nc">ExampleSensor</span><span class="p">(</span><span class="n">Entity</span><span class="p">):</span>
<span class="s">"""Representation of a Sensor."""</span>
<span class="decorator">@property</span>
<span class="keyword">def</span> <span class="function">name</span>(<span class="predefined-constant">self</span>):
<span class="docstring"><span class="delimiter">&quot;&quot;&quot;</span><span class="content">Return the name of the sensor.</span><span class="delimiter">&quot;&quot;&quot;</span></span>
<span class="keyword">return</span> <span class="string"><span class="delimiter">'</span><span class="content">Example Temperature</span><span class="delimiter">'</span></span>
<span class="nd">@property</span>
<span class="k">def</span> <span class="nf">name</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="s">"""Return the name of the sensor."""</span>
<span class="k">return</span> <span class="s">'Example Temperature'</span>
<span class="decorator">@property</span>
<span class="keyword">def</span> <span class="function">state</span>(<span class="predefined-constant">self</span>):
<span class="docstring"><span class="delimiter">&quot;&quot;&quot;</span><span class="content">Return the state of the sensor.</span><span class="delimiter">&quot;&quot;&quot;</span></span>
<span class="keyword">return</span> <span class="integer">23</span>
<span class="nd">@property</span>
<span class="k">def</span> <span class="nf">state</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="s">"""Return the state of the sensor."""</span>
<span class="k">return</span> <span class="mi">23</span>
<span class="decorator">@property</span>
<span class="keyword">def</span> <span class="function">unit_of_measurement</span>(<span class="predefined-constant">self</span>):
<span class="docstring"><span class="delimiter">&quot;&quot;&quot;</span><span class="content">Return the unit of measurement.</span><span class="delimiter">&quot;&quot;&quot;</span></span>
<span class="keyword">return</span> TEMP_CELSIUS
</pre></div>
</div>
<span class="nd">@property</span>
<span class="k">def</span> <span class="nf">unit_of_measurement</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="s">"""Return the unit of measurement."""</span>
<span class="k">return</span> <span class="n">TEMP_CELSIUS</span>
</code></pre>
</div>

218
developers/python_api/index.html
View file

@ -89,210 +89,186 @@
<hr class="divider">
<p>In the package <a href="https://github.com/home-assistant/home-assistant/blob/master/homeassistant/remote.py"><code>homeassistant.remote</code></a> a Python API on top of the <a href="/developers/api/">HTTP API</a> can be found.</p>
<p>In the package <a href="https://github.com/home-assistant/home-assistant/blob/master/homeassistant/remote.py"><code class="highlighter-rouge">homeassistant.remote</code></a> a Python API on top of the <a href="/developers/api/">HTTP API</a> can be found.</p>
<p>This page is not a full documentation it’s more a collection of some example. A simple way to get all current entities is to visit the “Set State” page in the “Developer Tools”. For the examples below just choose one from the available entries. Here the sensor <code>sensor.office_temperature</code> and the switch <code>switch.livingroom_pin_2</code> are used.</p>
<p>This page is not a full documentation it’s more a collection of some example. A simple way to get all current entities is to visit the “Set State” page in the “Developer Tools”. For the examples below just choose one from the available entries. Here the sensor <code class="highlighter-rouge">sensor.office_temperature</code> and the switch <code class="highlighter-rouge">switch.livingroom_pin_2</code> are used.</p>
<p>First import the module and setup the basics.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre><span class="keyword">import</span> <span class="include">homeassistant.remote</span> <span class="keyword">as</span> remote
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="kn">import</span> <span class="nn">homeassistant.remote</span> <span class="kn">as</span> <span class="nn">remote</span>
api = remote.API(<span class="string"><span class="delimiter">'</span><span class="content">127.1.0.1</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">password</span><span class="delimiter">'</span></span>)
print(remote.validate_api(api))
</pre></div>
</div>
<span class="n">api</span> <span class="o">=</span> <span class="n">remote</span><span class="o">.</span><span class="n">API</span><span class="p">(</span><span class="s">'127.1.0.1'</span><span class="p">,</span> <span class="s">'password'</span><span class="p">)</span>
<span class="k">print</span><span class="p">(</span><span class="n">remote</span><span class="o">.</span><span class="n">validate_api</span><span class="p">(</span><span class="n">api</span><span class="p">))</span>
</code></pre>
</div>
<p>This snippets shows how to use the <code>homeassistant.remote</code> package in another way.</p>
<p>This snippets shows how to use the <code class="highlighter-rouge">homeassistant.remote</code> package in another way.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre><span class="keyword">import</span> <span class="include">homeassistant.remote</span> <span class="keyword">as</span> remote
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="kn">import</span> <span class="nn">homeassistant.remote</span> <span class="kn">as</span> <span class="nn">remote</span>
api = remote.API(<span class="string"><span class="delimiter">'</span><span class="content">127.1.0.1</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">password</span><span class="delimiter">'</span></span>)
hass = remote.HomeAssistant(api)
hass.start()
living_room = hass.states.get(<span class="string"><span class="delimiter">'</span><span class="content">group.living_room</span><span class="delimiter">'</span></span>)
</pre></div>
</div>
<span class="n">api</span> <span class="o">=</span> <span class="n">remote</span><span class="o">.</span><span class="n">API</span><span class="p">(</span><span class="s">'127.1.0.1'</span><span class="p">,</span> <span class="s">'password'</span><span class="p">)</span>
<span class="n">hass</span> <span class="o">=</span> <span class="n">remote</span><span class="o">.</span><span class="n">HomeAssistant</span><span class="p">(</span><span class="n">api</span><span class="p">)</span>
<span class="n">hass</span><span class="o">.</span><span class="n">start</span><span class="p">()</span>
<span class="n">living_room</span> <span class="o">=</span> <span class="n">hass</span><span class="o">.</span><span class="n">states</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s">'group.living_room'</span><span class="p">)</span>
</code></pre>
</div>
<h3><a class="title-link" name="get-configuration" href="#get-configuration"></a> Get configuration</h3>
<p>Get the current configuration of a Home Asssitant instance.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre><span class="keyword">import</span> <span class="include">homeassistant.remote</span> <span class="keyword">as</span> remote
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="kn">import</span> <span class="nn">homeassistant.remote</span> <span class="kn">as</span> <span class="nn">remote</span>
api = remote.API(<span class="string"><span class="delimiter">'</span><span class="content">127.1.0.1</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">password</span><span class="delimiter">'</span></span>)
<span class="n">api</span> <span class="o">=</span> <span class="n">remote</span><span class="o">.</span><span class="n">API</span><span class="p">(</span><span class="s">'127.1.0.1'</span><span class="p">,</span> <span class="s">'password'</span><span class="p">)</span>
print(remote.get_config(api))
</pre></div>
</div>
<span class="k">print</span><span class="p">(</span><span class="n">remote</span><span class="o">.</span><span class="n">get_config</span><span class="p">(</span><span class="n">api</span><span class="p">))</span>
</code></pre>
</div>
<h3><a class="title-link" name="get-details-about-services-events-and-entitites" href="#get-details-about-services-events-and-entitites"></a> Get details about services, events, and entitites</h3>
<p>Similar to the output in the “Developer Tools” of the frontend.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre><span class="keyword">import</span> <span class="include">homeassistant.remote</span> <span class="keyword">as</span> remote
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="kn">import</span> <span class="nn">homeassistant.remote</span> <span class="kn">as</span> <span class="nn">remote</span>
api = remote.API(<span class="string"><span class="delimiter">'</span><span class="content">127.1.0.1</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">YOUR_PASSWORD</span><span class="delimiter">'</span></span>)
<span class="n">api</span> <span class="o">=</span> <span class="n">remote</span><span class="o">.</span><span class="n">API</span><span class="p">(</span><span class="s">'127.1.0.1'</span><span class="p">,</span> <span class="s">'YOUR_PASSWORD'</span><span class="p">)</span>
print(<span class="string"><span class="delimiter">'</span><span class="content">-- Available services:</span><span class="delimiter">'</span></span>)
services = remote.get_services(api)
<span class="keyword">for</span> service <span class="keyword">in</span> services:
print(service[<span class="string"><span class="delimiter">'</span><span class="content">services</span><span class="delimiter">'</span></span>])
<span class="k">print</span><span class="p">(</span><span class="s">'-- Available services:'</span><span class="p">)</span>
<span class="n">services</span> <span class="o">=</span> <span class="n">remote</span><span class="o">.</span><span class="n">get_services</span><span class="p">(</span><span class="n">api</span><span class="p">)</span>
<span class="k">for</span> <span class="n">service</span> <span class="ow">in</span> <span class="n">services</span><span class="p">:</span>
<span class="k">print</span><span class="p">(</span><span class="n">service</span><span class="p">[</span><span class="s">'services'</span><span class="p">])</span>
print(<span class="string"><span class="delimiter">'</span><span class="char">\n</span><span class="content">-- Available events:</span><span class="delimiter">'</span></span>)
events = remote.get_event_listeners(api)
<span class="keyword">for</span> event <span class="keyword">in</span> events:
print(event)
<span class="k">print</span><span class="p">(</span><span class="s">'</span><span class="se">\n</span><span class="s">-- Available events:'</span><span class="p">)</span>
<span class="n">events</span> <span class="o">=</span> <span class="n">remote</span><span class="o">.</span><span class="n">get_event_listeners</span><span class="p">(</span><span class="n">api</span><span class="p">)</span>
<span class="k">for</span> <span class="n">event</span> <span class="ow">in</span> <span class="n">events</span><span class="p">:</span>
<span class="k">print</span><span class="p">(</span><span class="n">event</span><span class="p">)</span>
print(<span class="string"><span class="delimiter">'</span><span class="char">\n</span><span class="content">-- Available entities:</span><span class="delimiter">'</span></span>)
entities = remote.get_states(api)
<span class="keyword">for</span> entity <span class="keyword">in</span> entities:
print(entity)
</pre></div>
</div>
<span class="k">print</span><span class="p">(</span><span class="s">'</span><span class="se">\n</span><span class="s">-- Available entities:'</span><span class="p">)</span>
<span class="n">entities</span> <span class="o">=</span> <span class="n">remote</span><span class="o">.</span><span class="n">get_states</span><span class="p">(</span><span class="n">api</span><span class="p">)</span>
<span class="k">for</span> <span class="n">entity</span> <span class="ow">in</span> <span class="n">entities</span><span class="p">:</span>
<span class="k">print</span><span class="p">(</span><span class="n">entity</span><span class="p">)</span>
</code></pre>
</div>
<h3><a class="title-link" name="get-the-state-of-an-entity" href="#get-the-state-of-an-entity"></a> Get the state of an entity</h3>
<p>To get the details of a single entity the <code>get_state</code> method is used.</p>
<p>To get the details of a single entity the <code class="highlighter-rouge">get_state</code> method is used.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre><span class="keyword">import</span> <span class="include">homeassistant.remote</span> <span class="keyword">as</span> remote
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="kn">import</span> <span class="nn">homeassistant.remote</span> <span class="kn">as</span> <span class="nn">remote</span>
api = remote.API(<span class="string"><span class="delimiter">'</span><span class="content">127.1.0.1</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">YOUR_PASSWORD</span><span class="delimiter">'</span></span>)
office_temperature = remote.get_state(api, <span class="string"><span class="delimiter">'</span><span class="content">sensor.office_temperature</span><span class="delimiter">'</span></span>)
print(<span class="string"><span class="delimiter">'</span><span class="content">{} is {} {}.</span><span class="delimiter">'</span></span>.format(office_temperature.attributes[<span class="string"><span class="delimiter">'</span><span class="content">friendly_name</span><span class="delimiter">'</span></span>],
office_temperature.state,
office_temperature.attributes[<span class="string"><span class="delimiter">'</span><span class="content">unit_of_measurement</span><span class="delimiter">'</span></span>]
)
)
</pre></div>
</div>
<span class="n">api</span> <span class="o">=</span> <span class="n">remote</span><span class="o">.</span><span class="n">API</span><span class="p">(</span><span class="s">'127.1.0.1'</span><span class="p">,</span> <span class="s">'YOUR_PASSWORD'</span><span class="p">)</span>
<span class="n">office_temperature</span> <span class="o">=</span> <span class="n">remote</span><span class="o">.</span><span class="n">get_state</span><span class="p">(</span><span class="n">api</span><span class="p">,</span> <span class="s">'sensor.office_temperature'</span><span class="p">)</span>
<span class="k">print</span><span class="p">(</span><span class="s">'{} is {} {}.'</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">office_temperature</span><span class="o">.</span><span class="n">attributes</span><span class="p">[</span><span class="s">'friendly_name'</span><span class="p">],</span>
<span class="n">office_temperature</span><span class="o">.</span><span class="n">state</span><span class="p">,</span>
<span class="n">office_temperature</span><span class="o">.</span><span class="n">attributes</span><span class="p">[</span><span class="s">'unit_of_measurement'</span><span class="p">]</span>
<span class="p">)</span>
<span class="p">)</span>
</code></pre>
</div>
<p>The output is composed out of the details which are stored for this entity.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>Office Temperature is 19 °C.
</pre></div>
</div>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code>Office Temperature is 19 °C.
</code></pre>
</div>
<p>The exact same thing is working for a switch. The difference is that both entities have different attributes.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre><span class="keyword">import</span> <span class="include">homeassistant.remote</span> <span class="keyword">as</span> remote
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="kn">import</span> <span class="nn">homeassistant.remote</span> <span class="kn">as</span> <span class="nn">remote</span>
api = remote.API(<span class="string"><span class="delimiter">'</span><span class="content">127.1.0.1</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">YOUR_PASSWORD</span><span class="delimiter">'</span></span>)
switch_livingroom = remote.get_state(api, <span class="string"><span class="delimiter">'</span><span class="content">switch.livingroom_pin_2</span><span class="delimiter">'</span></span>)
print(<span class="string"><span class="delimiter">'</span><span class="content">{} is {}.</span><span class="delimiter">'</span></span>.format(switch_livingroom.attributes[<span class="string"><span class="delimiter">'</span><span class="content">friendly_name</span><span class="delimiter">'</span></span>],
switch_livingroom.state
)
)
</pre></div>
</div>
<span class="n">api</span> <span class="o">=</span> <span class="n">remote</span><span class="o">.</span><span class="n">API</span><span class="p">(</span><span class="s">'127.1.0.1'</span><span class="p">,</span> <span class="s">'YOUR_PASSWORD'</span><span class="p">)</span>
<span class="n">switch_livingroom</span> <span class="o">=</span> <span class="n">remote</span><span class="o">.</span><span class="n">get_state</span><span class="p">(</span><span class="n">api</span><span class="p">,</span> <span class="s">'switch.livingroom_pin_2'</span><span class="p">)</span>
<span class="k">print</span><span class="p">(</span><span class="s">'{} is {}.'</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">switch_livingroom</span><span class="o">.</span><span class="n">attributes</span><span class="p">[</span><span class="s">'friendly_name'</span><span class="p">],</span>
<span class="n">switch_livingroom</span><span class="o">.</span><span class="n">state</span>
<span class="p">)</span>
<span class="p">)</span>
</code></pre>
</div>
<h3><a class="title-link" name="set-the-state-of-an-entity" href="#set-the-state-of-an-entity"></a> Set the state of an entity</h3>
<p>Of course, it’s possible to set the state.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre><span class="keyword">import</span> <span class="include">homeassistant.remote</span> <span class="keyword">as</span> remote
<span class="keyword">from</span> <span class="include">homeassistant.const</span> <span class="keyword">import</span> <span class="include">STATE_ON</span>
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="kn">import</span> <span class="nn">homeassistant.remote</span> <span class="kn">as</span> <span class="nn">remote</span>
<span class="kn">from</span> <span class="nn">homeassistant.const</span> <span class="kn">import</span> <span class="n">STATE_ON</span>
api = remote.API(<span class="string"><span class="delimiter">'</span><span class="content">127.1.0.1</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">YOUR_PASSWORD</span><span class="delimiter">'</span></span>)
remote.set_state(api, <span class="string"><span class="delimiter">'</span><span class="content">sensor.office_temperature</span><span class="delimiter">'</span></span>, new_state=<span class="integer">123</span>)
remote.set_state(api, <span class="string"><span class="delimiter">'</span><span class="content">switch.livingroom_pin_2</span><span class="delimiter">'</span></span>, new_state=STATE_ON)
</pre></div>
</div>
<span class="n">api</span> <span class="o">=</span> <span class="n">remote</span><span class="o">.</span><span class="n">API</span><span class="p">(</span><span class="s">'127.1.0.1'</span><span class="p">,</span> <span class="s">'YOUR_PASSWORD'</span><span class="p">)</span>
<span class="n">remote</span><span class="o">.</span><span class="n">set_state</span><span class="p">(</span><span class="n">api</span><span class="p">,</span> <span class="s">'sensor.office_temperature'</span><span class="p">,</span> <span class="n">new_state</span><span class="o">=</span><span class="mi">123</span><span class="p">)</span>
<span class="n">remote</span><span class="o">.</span><span class="n">set_state</span><span class="p">(</span><span class="n">api</span><span class="p">,</span> <span class="s">'switch.livingroom_pin_2'</span><span class="p">,</span> <span class="n">new_state</span><span class="o">=</span><span class="n">STATE_ON</span><span class="p">)</span>
</code></pre>
</div>
<p>The state will be set to those value until the next update occurs.</p>
<h3><a class="title-link" name="blinking-all-entites-of-a-domain" href="#blinking-all-entites-of-a-domain"></a> Blinking all entites of a domain</h3>
<p>If you want to turn on all entities of a domain, just use a service which was retrieved by <code>get_services</code>.</p>
<p>If you want to turn on all entities of a domain, just use a service which was retrieved by <code class="highlighter-rouge">get_services</code>.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre><span class="keyword">import</span> <span class="include">time</span>
<span class="keyword">import</span> <span class="include">homeassistant.remote</span> <span class="keyword">as</span> remote
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="kn">import</span> <span class="nn">time</span>
<span class="kn">import</span> <span class="nn">homeassistant.remote</span> <span class="kn">as</span> <span class="nn">remote</span>
api = remote.API(<span class="string"><span class="delimiter">'</span><span class="content">127.1.0.1</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">YOUR_PASSWORD</span><span class="delimiter">'</span></span>)
domain = <span class="string"><span class="delimiter">'</span><span class="content">switch</span><span class="delimiter">'</span></span>
<span class="n">api</span> <span class="o">=</span> <span class="n">remote</span><span class="o">.</span><span class="n">API</span><span class="p">(</span><span class="s">'127.1.0.1'</span><span class="p">,</span> <span class="s">'YOUR_PASSWORD'</span><span class="p">)</span>
<span class="n">domain</span> <span class="o">=</span> <span class="s">'switch'</span>
remote.call_service(api, domain, <span class="string"><span class="delimiter">'</span><span class="content">turn_on</span><span class="delimiter">'</span></span>)
time.sleep(<span class="integer">10</span>)
remote.call_service(api, domain, <span class="string"><span class="delimiter">'</span><span class="content">turn_off</span><span class="delimiter">'</span></span>)
</pre></div>
</div>
<span class="n">remote</span><span class="o">.</span><span class="n">call_service</span><span class="p">(</span><span class="n">api</span><span class="p">,</span> <span class="n">domain</span><span class="p">,</span> <span class="s">'turn_on'</span><span class="p">)</span>
<span class="n">time</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="mi">10</span><span class="p">)</span>
<span class="n">remote</span><span class="o">.</span><span class="n">call_service</span><span class="p">(</span><span class="n">api</span><span class="p">,</span> <span class="n">domain</span><span class="p">,</span> <span class="s">'turn_off'</span><span class="p">)</span>
</code></pre>
</div>
<h3><a class="title-link" name="control-a-single-entity" href="#control-a-single-entity"></a> Control a single entity</h3>
<p>To turn on or off a single switch. The ID of the entity is needed as attribute.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre><span class="keyword">import</span> <span class="include">time</span>
<span class="keyword">import</span> <span class="include">homeassistant.remote</span> <span class="keyword">as</span> remote
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="kn">import</span> <span class="nn">time</span>
<span class="kn">import</span> <span class="nn">homeassistant.remote</span> <span class="kn">as</span> <span class="nn">remote</span>
api = remote.API(<span class="string"><span class="delimiter">'</span><span class="content">127.1.0.1</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">YOUR_PASSWORD</span><span class="delimiter">'</span></span>)
domain = <span class="string"><span class="delimiter">'</span><span class="content">switch</span><span class="delimiter">'</span></span>
switch_name = <span class="string"><span class="delimiter">'</span><span class="content">switch.livingroom_pin_2</span><span class="delimiter">'</span></span>
<span class="n">api</span> <span class="o">=</span> <span class="n">remote</span><span class="o">.</span><span class="n">API</span><span class="p">(</span><span class="s">'127.1.0.1'</span><span class="p">,</span> <span class="s">'YOUR_PASSWORD'</span><span class="p">)</span>
<span class="n">domain</span> <span class="o">=</span> <span class="s">'switch'</span>
<span class="n">switch_name</span> <span class="o">=</span> <span class="s">'switch.livingroom_pin_2'</span>
remote.call_service(api, domain, <span class="string"><span class="delimiter">'</span><span class="content">turn_on</span><span class="delimiter">'</span></span>, {<span class="string"><span class="delimiter">'</span><span class="content">entity_id</span><span class="delimiter">'</span></span>: <span class="string"><span class="delimiter">'</span><span class="content">{}</span><span class="delimiter">'</span></span>.format(switch_name)})
time.sleep(<span class="integer">5</span>)
remote.call_service(api, domain, <span class="string"><span class="delimiter">'</span><span class="content">turn_off</span><span class="delimiter">'</span></span>, {<span class="string"><span class="delimiter">'</span><span class="content">entity_id</span><span class="delimiter">'</span></span>: <span class="string"><span class="delimiter">'</span><span class="content">{}</span><span class="delimiter">'</span></span>.format(switch_name)})
</pre></div>
</div>
<span class="n">remote</span><span class="o">.</span><span class="n">call_service</span><span class="p">(</span><span class="n">api</span><span class="p">,</span> <span class="n">domain</span><span class="p">,</span> <span class="s">'turn_on'</span><span class="p">,</span> <span class="p">{</span><span class="s">'entity_id'</span><span class="p">:</span> <span class="s">'{}'</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">switch_name</span><span class="p">)})</span>
<span class="n">time</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="mi">5</span><span class="p">)</span>
<span class="n">remote</span><span class="o">.</span><span class="n">call_service</span><span class="p">(</span><span class="n">api</span><span class="p">,</span> <span class="n">domain</span><span class="p">,</span> <span class="s">'turn_off'</span><span class="p">,</span> <span class="p">{</span><span class="s">'entity_id'</span><span class="p">:</span> <span class="s">'{}'</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">switch_name</span><span class="p">)})</span>
</code></pre>
</div>
<h3><a class="title-link" name="specify-a-timeout" href="#specify-a-timeout"></a> Specify a timeout</h3>
<p>The default timeout for an API call with <code>call_service</code> is 5 seconds. Service<br />
taking longer than this to return will raise<br />
<code>homeassistant.exceptions.HomeAssistantError: Timeout</code> unless provided with a<br />
<p>The default timeout for an API call with <code class="highlighter-rouge">call_service</code> is 5 seconds. Service
taking longer than this to return will raise
<code class="highlighter-rouge">homeassistant.exceptions.HomeAssistantError: Timeout</code> unless provided with a
longer timeout.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre><span class="keyword">import</span> <span class="include">homeassistant.remote</span> <span class="keyword">as</span> remote
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="kn">import</span> <span class="nn">homeassistant.remote</span> <span class="kn">as</span> <span class="nn">remote</span>
api = remote.API(<span class="string"><span class="delimiter">'</span><span class="content">host</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">password</span><span class="delimiter">'</span></span>)
domain = <span class="string"><span class="delimiter">'</span><span class="content">switch</span><span class="delimiter">'</span></span>
<span class="n">api</span> <span class="o">=</span> <span class="n">remote</span><span class="o">.</span><span class="n">API</span><span class="p">(</span><span class="s">'host'</span><span class="p">,</span> <span class="s">'password'</span><span class="p">)</span>
<span class="n">domain</span> <span class="o">=</span> <span class="s">'switch'</span>
<span class="comment"># Assuming switch.timeout_switch takes 10 seconds to return</span>
switch_name = <span class="string"><span class="delimiter">'</span><span class="content">switch.timeout_switch</span><span class="delimiter">'</span></span>
<span class="c"># Assuming switch.timeout_switch takes 10 seconds to return</span>
<span class="n">switch_name</span> <span class="o">=</span> <span class="s">'switch.timeout_switch'</span>
<span class="comment"># Raises homeassistant.exceptions.HomeAssistantError: Timeout when talking to</span>
remote.call_service(api, domain, <span class="string"><span class="delimiter">'</span><span class="content">turn_on</span><span class="delimiter">'</span></span>, {<span class="string"><span class="delimiter">'</span><span class="content">entity_id</span><span class="delimiter">'</span></span>: switch_name})
<span class="c"># Raises homeassistant.exceptions.HomeAssistantError: Timeout when talking to</span>
<span class="n">remote</span><span class="o">.</span><span class="n">call_service</span><span class="p">(</span><span class="n">api</span><span class="p">,</span> <span class="n">domain</span><span class="p">,</span> <span class="s">'turn_on'</span><span class="p">,</span> <span class="p">{</span><span class="s">'entity_id'</span><span class="p">:</span> <span class="n">switch_name</span><span class="p">})</span>
<span class="comment"># Runs withous exception</span>
remote.call_service(api, domain, <span class="string"><span class="delimiter">'</span><span class="content">turn_on</span><span class="delimiter">'</span></span>, {<span class="string"><span class="delimiter">'</span><span class="content">entity_id</span><span class="delimiter">'</span></span>: switch_name},
timeout=<span class="integer">11</span>)
</pre></div>
</div>
<span class="c"># Runs withous exception</span>
<span class="n">remote</span><span class="o">.</span><span class="n">call_service</span><span class="p">(</span><span class="n">api</span><span class="p">,</span> <span class="n">domain</span><span class="p">,</span> <span class="s">'turn_on'</span><span class="p">,</span> <span class="p">{</span><span class="s">'entity_id'</span><span class="p">:</span> <span class="n">switch_name</span><span class="p">},</span>
<span class="n">timeout</span><span class="o">=</span><span class="mi">11</span><span class="p">)</span>
</code></pre>
</div>
<h3><a class="title-link" name="send-a-notification" href="#send-a-notification"></a> Send a notification</h3>
<p>The example uses the jabber notification platform to send a single message to the given recipient in the <code>configuration.yaml</code> file.</p>
<p>The example uses the jabber notification platform to send a single message to the given recipient in the <code class="highlighter-rouge">configuration.yaml</code> file.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre><span class="keyword">import</span> <span class="include">homeassistant.remote</span> <span class="keyword">as</span> remote
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="kn">import</span> <span class="nn">homeassistant.remote</span> <span class="kn">as</span> <span class="nn">remote</span>
api = remote.API(<span class="string"><span class="delimiter">'</span><span class="content">127.1.0.1</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">YOUR_PASSWORD</span><span class="delimiter">'</span></span>)
domain = <span class="string"><span class="delimiter">'</span><span class="content">notify</span><span class="delimiter">'</span></span>
data = {<span class="string"><span class="delimiter">&quot;</span><span class="content">title</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">Test</span><span class="delimiter">&quot;</span></span>, <span class="string"><span class="delimiter">&quot;</span><span class="content">message</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">A simple test message from HA.</span><span class="delimiter">&quot;</span></span>}
<span class="n">api</span> <span class="o">=</span> <span class="n">remote</span><span class="o">.</span><span class="n">API</span><span class="p">(</span><span class="s">'127.1.0.1'</span><span class="p">,</span> <span class="s">'YOUR_PASSWORD'</span><span class="p">)</span>
<span class="n">domain</span> <span class="o">=</span> <span class="s">'notify'</span>
<span class="n">data</span> <span class="o">=</span> <span class="p">{</span><span class="s">"title"</span><span class="p">:</span><span class="s">"Test"</span><span class="p">,</span> <span class="s">"message"</span><span class="p">:</span><span class="s">"A simple test message from HA."</span><span class="p">}</span>
remote.call_service(api, domain, <span class="string"><span class="delimiter">'</span><span class="content">jabber</span><span class="delimiter">'</span></span>, data)
</pre></div>
</div>
<span class="n">remote</span><span class="o">.</span><span class="n">call_service</span><span class="p">(</span><span class="n">api</span><span class="p">,</span> <span class="n">domain</span><span class="p">,</span> <span class="s">'jabber'</span><span class="p">,</span> <span class="n">data</span><span class="p">)</span>
</code></pre>
</div>
<p>For more details please check the source of <a href="https://github.com/home-assistant/home-assistant/blob/master/homeassistant/remote.py">homeassistant.remote</a>.</p>

24
developers/releasing/index.html
View file

@ -94,28 +94,28 @@
<h3><a class="title-link" name="github" href="#github"></a> GitHub</h3>
<ol>
<li>Create a pull request from <code>dev</code> to <code>master</code> with the upcoming release number as title.</li>
<li>Merge <code>master</code> into <code>dev</code> to make the PR mergable. PR message contains intro, highlighting major changes, and an overview of all changes tagging each author.</li>
<li>Update <code>homeassistant/const.py</code> with the correct version number (remove the the <code>dev</code> tag) and push that commit.</li>
<li>Create a pull request from <code class="highlighter-rouge">dev</code> to <code class="highlighter-rouge">master</code> with the upcoming release number as title.</li>
<li>Merge <code class="highlighter-rouge">master</code> into <code class="highlighter-rouge">dev</code> to make the PR mergable. PR message contains intro, highlighting major changes, and an overview of all changes tagging each author.</li>
<li>Update <code class="highlighter-rouge">homeassistant/const.py</code> with the correct version number (remove the the <code class="highlighter-rouge">dev</code> tag) and push that commit.</li>
<li>Merge pull request.</li>
<li>Then, after merged, push another update to <code>dev</code> of <code>homeassistant/const.py</code> that includes the next version with the <code>dev</code> tag. Add a meaningful commit message like “Version bump to X”. This commit acts as marker for the next release.</li>
<li>Go to <a href="https://github.com/home-assistant/home-assistant/releases">releases</a> and tag a new release on the <code>master</code> branch. “Tag version” and “Release title” are the version number (<code>O.x</code> for major version, <code>0.x.y</code> for minor and bug fix releases). Release description is the text from PR. Press “Publish release” to finish the process.</li>
<li>Then, after merged, push another update to <code class="highlighter-rouge">dev</code> of <code class="highlighter-rouge">homeassistant/const.py</code> that includes the next version with the <code class="highlighter-rouge">dev</code> tag. Add a meaningful commit message like “Version bump to X”. This commit acts as marker for the next release.</li>
<li>Go to <a href="https://github.com/home-assistant/home-assistant/releases">releases</a> and tag a new release on the <code class="highlighter-rouge">master</code> branch. “Tag version” and “Release title” are the version number (<code class="highlighter-rouge">O.x</code> for major version, <code class="highlighter-rouge">0.x.y</code> for minor and bug fix releases). Release description is the text from PR. Press “Publish release” to finish the process.</li>
</ol>
<h3><a class="title-link" name="website" href="#website"></a> Website</h3>
<ol>
<li>Create a blog post in <code>next</code> and base it on the text of the PR in the main repository. Add images, additional text, links, etc. if it adds value. Tag each platform/component in message to documentation.</li>
<li>Create missing documentation as stumbs in <code>next</code>.</li>
<li>Update the link on the frontpage (<code>source/index.html</code>) to link to the new release blog post and version number.</li>
<li>Create a pull request from <code>next</code> to <code>master</code> with the upcoming release number as title.</li>
<li>Merge <code>master</code> into <code>next</code> (<code>$ git checkout next &amp;&amp; git merge master</code>) to make the PR mergable.</li>
<li>Merge pull request (blog post, updated frontpage, and all new documentation) to <code>master</code>.</li>
<li>Create a blog post in <code class="highlighter-rouge">next</code> and base it on the text of the PR in the main repository. Add images, additional text, links, etc. if it adds value. Tag each platform/component in message to documentation.</li>
<li>Create missing documentation as stumbs in <code class="highlighter-rouge">next</code>.</li>
<li>Update the link on the frontpage (<code class="highlighter-rouge">source/index.html</code>) to link to the new release blog post and version number.</li>
<li>Create a pull request from <code class="highlighter-rouge">next</code> to <code class="highlighter-rouge">master</code> with the upcoming release number as title.</li>
<li>Merge <code class="highlighter-rouge">master</code> into <code class="highlighter-rouge">next</code> (<code class="highlighter-rouge">$ git checkout next &amp;&amp; git merge master</code>) to make the PR mergable.</li>
<li>Merge pull request (blog post, updated frontpage, and all new documentation) to <code class="highlighter-rouge">master</code>.</li>
</ol>
<h3><a class="title-link" name="python-package-index" href="#python-package-index"></a> Python Package Index</h3>
<p>Checkout the <code>master</code> branch and run <code>script/release</code> to publish the new release on <a href="https://pypi.python.org">Python Package Index</a>.</p>
<p>Checkout the <code class="highlighter-rouge">master</code> branch and run <code class="highlighter-rouge">script/release</code> to publish the new release on <a href="https://pypi.python.org">Python Package Index</a>.</p>
<h3><a class="title-link" name="social-media" href="#social-media"></a> Social media</h3>

620
developers/rest_api/index.html
View file

@ -96,36 +96,32 @@
<li>http://IP_ADDRESS:8123/api/ is a Rest API.</li>
</ul>
<p>The API accepts and returns only JSON encoded objects. All API calls have to be accompanied by the header <code>X-HA-Access: YOUR_PASSWORD</code> (YOUR_PASSWORD as specified in your <code>configuration.yaml</code> file in the <a href="/components/http/"><code>http:</code> section</a>).</p>
<p>The API accepts and returns only JSON encoded objects. All API calls have to be accompanied by the header <code class="highlighter-rouge">X-HA-Access: YOUR_PASSWORD</code> (YOUR_PASSWORD as specified in your <code class="highlighter-rouge">configuration.yaml</code> file in the <a href="/components/http/"><code class="highlighter-rouge">http:</code> section</a>).</p>
<p>There are multiple ways to consume the Home Assistant Rest API. One is with <code>curl</code>:</p>
<p>There are multiple ways to consume the Home Assistant Rest API. One is with <code class="highlighter-rouge">curl</code>:</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>curl -X GET \
-H &quot;x-ha-access: YOUR_PASSWORD&quot; \
-H &quot;Content-Type: application/json&quot; \
<div class="language-bash highlighter-rouge"><pre class="highlight"><code>curl -X GET <span class="se">\</span>
-H <span class="s2">"x-ha-access: YOUR_PASSWORD"</span> <span class="se">\</span>
-H <span class="s2">"Content-Type: application/json"</span> <span class="se">\</span>
http://IP_ADDRESS:8123/ENDPOINT
</pre></div>
</div>
</code></pre>
</div>
<p>Another option is to use Python and the <a href="http://docs.python-requests.org/en/latest/">Requests</a> module.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre><span class="keyword">from</span> <span class="include">requests</span> <span class="keyword">import</span> <span class="include">get</span>
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="kn">from</span> <span class="nn">requests</span> <span class="kn">import</span> <span class="n">get</span>
url = <span class="string"><span class="delimiter">'</span><span class="content">http://localhost:8123/ENDPOINT</span><span class="delimiter">'</span></span>
headers = {<span class="string"><span class="delimiter">'</span><span class="content">x-ha-access</span><span class="delimiter">'</span></span>: <span class="string"><span class="delimiter">'</span><span class="content">YOUR_PASSWORD</span><span class="delimiter">'</span></span>,
<span class="string"><span class="delimiter">'</span><span class="content">content-type</span><span class="delimiter">'</span></span>: <span class="string"><span class="delimiter">'</span><span class="content">application/json</span><span class="delimiter">'</span></span>}
<span class="n">url</span> <span class="o">=</span> <span class="s">'http://localhost:8123/ENDPOINT'</span>
<span class="n">headers</span> <span class="o">=</span> <span class="p">{</span><span class="s">'x-ha-access'</span><span class="p">:</span> <span class="s">'YOUR_PASSWORD'</span><span class="p">,</span>
<span class="s">'content-type'</span><span class="p">:</span> <span class="s">'application/json'</span><span class="p">}</span>
response = get(url, headers=headers)
print(response.text)
</pre></div>
</div>
<span class="n">response</span> <span class="o">=</span> <span class="n">get</span><span class="p">(</span><span class="n">url</span><span class="p">,</span> <span class="n">headers</span><span class="o">=</span><span class="n">headers</span><span class="p">)</span>
<span class="k">print</span><span class="p">(</span><span class="n">response</span><span class="o">.</span><span class="n">text</span><span class="p">)</span>
</code></pre>
</div>
<p class="note">
You can append <code>?password=YOUR_PASSWORD</code> to any url to log in automatically.
You can append <code class="highlighter-rouge">?password=YOUR_PASSWORD</code> to any url to log in automatically.
</p>
<p>Successful calls will return status code 200 or 201. Other status codes that can return are:</p>
@ -144,309 +140,265 @@ You can append <code>?password=YOUR_PASSWORD</code> to any url to log in automat
<h4><a class="title-link" name="get-api" href="#get-api"></a> GET /api/</h4>
<p>Returns message if API is up and running.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>{
<span class="key"><span class="delimiter">&quot;</span><span class="content">message</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">API running.</span><span class="delimiter">&quot;</span></span>
}
</pre></div>
</div>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"message"</span><span class="p">:</span><span class="w"> </span><span class="s2">"API running."</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<p>Sample <code>curl</code> command:</p>
<p>Sample <code class="highlighter-rouge">curl</code> command:</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>$ curl -X GET -H &quot;x-ha-access: YOUR_PASSWORD&quot; \
-H &quot;Content-Type: application/json&quot; http://localhost:8123/api/
</pre></div>
</div>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>curl -X GET -H <span class="s2">"x-ha-access: YOUR_PASSWORD"</span> <span class="se">\</span>
-H <span class="s2">"Content-Type: application/json"</span> http://localhost:8123/api/
</code></pre>
</div>
<h4><a class="title-link" name="get-apiconfig" href="#get-apiconfig"></a> GET /api/config</h4>
<p>Returns the current configuration as JSON.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>{
<span class="key"><span class="delimiter">&quot;</span><span class="content">components</span><span class="delimiter">&quot;</span></span>: [
<span class="string"><span class="delimiter">&quot;</span><span class="content">recorder</span><span class="delimiter">&quot;</span></span>,
<span class="string"><span class="delimiter">&quot;</span><span class="content">http</span><span class="delimiter">&quot;</span></span>,
<span class="string"><span class="delimiter">&quot;</span><span class="content">sensor.time_date</span><span class="delimiter">&quot;</span></span>,
<span class="string"><span class="delimiter">&quot;</span><span class="content">api</span><span class="delimiter">&quot;</span></span>,
<span class="string"><span class="delimiter">&quot;</span><span class="content">frontend</span><span class="delimiter">&quot;</span></span>,
<span class="string"><span class="delimiter">&quot;</span><span class="content">sun</span><span class="delimiter">&quot;</span></span>,
<span class="string"><span class="delimiter">&quot;</span><span class="content">logbook</span><span class="delimiter">&quot;</span></span>,
<span class="string"><span class="delimiter">&quot;</span><span class="content">history</span><span class="delimiter">&quot;</span></span>,
<span class="string"><span class="delimiter">&quot;</span><span class="content">group</span><span class="delimiter">&quot;</span></span>,
<span class="string"><span class="delimiter">&quot;</span><span class="content">automation</span><span class="delimiter">&quot;</span></span>
],
<span class="key"><span class="delimiter">&quot;</span><span class="content">latitude</span><span class="delimiter">&quot;</span></span>: <span class="float">44.1234</span>,
<span class="key"><span class="delimiter">&quot;</span><span class="content">location_name</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">Home</span><span class="delimiter">&quot;</span></span>,
<span class="key"><span class="delimiter">&quot;</span><span class="content">longitude</span><span class="delimiter">&quot;</span></span>: <span class="float">5.5678</span>,
<span class="key"><span class="delimiter">&quot;</span><span class="content">unit_system</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">metric</span><span class="delimiter">&quot;</span></span>,
<span class="key"><span class="delimiter">&quot;</span><span class="content">time_zone</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">Europe/Zurich</span><span class="delimiter">&quot;</span></span>,
<span class="key"><span class="delimiter">&quot;</span><span class="content">version</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">0.8.0.dev0</span><span class="delimiter">&quot;</span></span>
}
</pre></div>
</div>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"components"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w">
</span><span class="s2">"recorder"</span><span class="p">,</span><span class="w">
</span><span class="s2">"http"</span><span class="p">,</span><span class="w">
</span><span class="s2">"sensor.time_date"</span><span class="p">,</span><span class="w">
</span><span class="s2">"api"</span><span class="p">,</span><span class="w">
</span><span class="s2">"frontend"</span><span class="p">,</span><span class="w">
</span><span class="s2">"sun"</span><span class="p">,</span><span class="w">
</span><span class="s2">"logbook"</span><span class="p">,</span><span class="w">
</span><span class="s2">"history"</span><span class="p">,</span><span class="w">
</span><span class="s2">"group"</span><span class="p">,</span><span class="w">
</span><span class="s2">"automation"</span><span class="w">
</span><span class="p">],</span><span class="w">
</span><span class="nt">"latitude"</span><span class="p">:</span><span class="w"> </span><span class="mf">44.1234</span><span class="p">,</span><span class="w">
</span><span class="nt">"location_name"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Home"</span><span class="p">,</span><span class="w">
</span><span class="nt">"longitude"</span><span class="p">:</span><span class="w"> </span><span class="mf">5.5678</span><span class="p">,</span><span class="w">
</span><span class="nt">"unit_system"</span><span class="p">:</span><span class="w"> </span><span class="s2">"metric"</span><span class="p">,</span><span class="w">
</span><span class="nt">"time_zone"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Europe/Zurich"</span><span class="p">,</span><span class="w">
</span><span class="nt">"version"</span><span class="p">:</span><span class="w"> </span><span class="s2">"0.8.0.dev0"</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<p>Sample <code>curl</code> command:</p>
<p>Sample <code class="highlighter-rouge">curl</code> command:</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>$ curl -X GET -H &quot;x-ha-access: YOUR_PASSWORD&quot; \
-H &quot;Content-Type: application/json&quot; http://localhost:8123/api/config
</pre></div>
</div>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>curl -X GET -H <span class="s2">"x-ha-access: YOUR_PASSWORD"</span> <span class="se">\</span>
-H <span class="s2">"Content-Type: application/json"</span> http://localhost:8123/api/config
</code></pre>
</div>
<h4><a class="title-link" name="get-apidiscovery_info" href="#get-apidiscovery_info"></a> GET /api/discovery_info</h4>
<p>Returns basic information about the Home Assistant instance as JSON.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>{
<span class="key"><span class="delimiter">&quot;</span><span class="content">base_url</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">http://127.0.0.1:8123</span><span class="delimiter">&quot;</span></span>,
<span class="key"><span class="delimiter">&quot;</span><span class="content">location_name</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">Home</span><span class="delimiter">&quot;</span></span>,
<span class="key"><span class="delimiter">&quot;</span><span class="content">requires_api_password</span><span class="delimiter">&quot;</span></span>: <span class="value">true</span>,
<span class="key"><span class="delimiter">&quot;</span><span class="content">version</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">0.20.0.dev0</span><span class="delimiter">&quot;</span></span>
}
</pre></div>
</div>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"base_url"</span><span class="p">:</span><span class="w"> </span><span class="s2">"http://127.0.0.1:8123"</span><span class="p">,</span><span class="w">
</span><span class="nt">"location_name"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Home"</span><span class="p">,</span><span class="w">
</span><span class="nt">"requires_api_password"</span><span class="p">:</span><span class="w"> </span><span class="kc">true</span><span class="p">,</span><span class="w">
</span><span class="nt">"version"</span><span class="p">:</span><span class="w"> </span><span class="s2">"0.20.0.dev0"</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<p>Sample <code>curl</code> command:</p>
<p>Sample <code class="highlighter-rouge">curl</code> command:</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>$ curl -X GET -H &quot;x-ha-access: YOUR_PASSWORD&quot; \
-H &quot;Content-Type: application/json&quot; http://localhost:8123/api/discovery_info
</pre></div>
</div>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>curl -X GET -H <span class="s2">"x-ha-access: YOUR_PASSWORD"</span> <span class="se">\</span>
-H <span class="s2">"Content-Type: application/json"</span> http://localhost:8123/api/discovery_info
</code></pre>
</div>
<h4><a class="title-link" name="get-apibootstrap" href="#get-apibootstrap"></a> GET /api/bootstrap</h4>
<p>Returns all data needed to bootstrap Home Assistant.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>{
<span class="key"><span class="delimiter">&quot;</span><span class="content">config</span><span class="delimiter">&quot;</span></span>: {<span class="error">.</span><span class="error">.</span><span class="error">.</span>},
<span class="key"><span class="delimiter">&quot;</span><span class="content">events</span><span class="delimiter">&quot;</span></span>: [<span class="error">.</span><span class="error">.</span><span class="error">.</span>],
<span class="key"><span class="delimiter">&quot;</span><span class="content">services</span><span class="delimiter">&quot;</span></span>: [<span class="error">.</span><span class="error">.</span><span class="error">.</span>],
<span class="key"><span class="delimiter">&quot;</span><span class="content">states</span><span class="delimiter">&quot;</span></span>: [<span class="error">.</span><span class="error">.</span><span class="error">.</span>]
}
</pre></div>
</div>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"config"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="err">...</span><span class="p">},</span><span class="w">
</span><span class="nt">"events"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="err">...</span><span class="p">],</span><span class="w">
</span><span class="nt">"services"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="err">...</span><span class="p">],</span><span class="w">
</span><span class="nt">"states"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="err">...</span><span class="p">]</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<p>Sample <code>curl</code> command:</p>
<p>Sample <code class="highlighter-rouge">curl</code> command:</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>$ curl -X GET -H &quot;x-ha-access: YOUR_PASSWORD&quot; \
-H &quot;Content-Type: application/json&quot; http://localhost:8123/api/bootstrap
</pre></div>
</div>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>curl -X GET -H <span class="s2">"x-ha-access: YOUR_PASSWORD"</span> <span class="se">\</span>
-H <span class="s2">"Content-Type: application/json"</span> http://localhost:8123/api/bootstrap
</code></pre>
</div>
<h4><a class="title-link" name="get-apievents" href="#get-apievents"></a> GET /api/events</h4>
<p>Returns an array of event objects. Each event object contain event name and listener count.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>[
{
<span class="key"><span class="delimiter">&quot;</span><span class="content">event</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">state_changed</span><span class="delimiter">&quot;</span></span>,
<span class="key"><span class="delimiter">&quot;</span><span class="content">listener_count</span><span class="delimiter">&quot;</span></span>: <span class="integer">5</span>
},
{
<span class="key"><span class="delimiter">&quot;</span><span class="content">event</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">time_changed</span><span class="delimiter">&quot;</span></span>,
<span class="key"><span class="delimiter">&quot;</span><span class="content">listener_count</span><span class="delimiter">&quot;</span></span>: <span class="integer">2</span>
}
]
</pre></div>
</div>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">[</span><span class="w">
</span><span class="p">{</span><span class="w">
</span><span class="nt">"event"</span><span class="p">:</span><span class="w"> </span><span class="s2">"state_changed"</span><span class="p">,</span><span class="w">
</span><span class="nt">"listener_count"</span><span class="p">:</span><span class="w"> </span><span class="mi">5</span><span class="w">
</span><span class="p">},</span><span class="w">
</span><span class="p">{</span><span class="w">
</span><span class="nt">"event"</span><span class="p">:</span><span class="w"> </span><span class="s2">"time_changed"</span><span class="p">,</span><span class="w">
</span><span class="nt">"listener_count"</span><span class="p">:</span><span class="w"> </span><span class="mi">2</span><span class="w">
</span><span class="p">}</span><span class="w">
</span><span class="p">]</span><span class="w">
</span></code></pre>
</div>
<p>Sample <code>curl</code> command:</p>
<p>Sample <code class="highlighter-rouge">curl</code> command:</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>$ curl -X GET -H &quot;x-ha-access: YOUR_PASSWORD&quot; \
-H &quot;Content-Type: application/json&quot; http://localhost:8123/api/events
</pre></div>
</div>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>curl -X GET -H <span class="s2">"x-ha-access: YOUR_PASSWORD"</span> <span class="se">\</span>
-H <span class="s2">"Content-Type: application/json"</span> http://localhost:8123/api/events
</code></pre>
</div>
<h4><a class="title-link" name="get-apiservices" href="#get-apiservices"></a> GET /api/services</h4>
<p>Returns an array of service objects. Each object contains the domain and which services it contains.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>[
{
<span class="key"><span class="delimiter">&quot;</span><span class="content">domain</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">browser</span><span class="delimiter">&quot;</span></span>,
<span class="key"><span class="delimiter">&quot;</span><span class="content">services</span><span class="delimiter">&quot;</span></span>: [
<span class="string"><span class="delimiter">&quot;</span><span class="content">browse_url</span><span class="delimiter">&quot;</span></span>
]
},
{
<span class="key"><span class="delimiter">&quot;</span><span class="content">domain</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">keyboard</span><span class="delimiter">&quot;</span></span>,
<span class="key"><span class="delimiter">&quot;</span><span class="content">services</span><span class="delimiter">&quot;</span></span>: [
<span class="string"><span class="delimiter">&quot;</span><span class="content">volume_up</span><span class="delimiter">&quot;</span></span>,
<span class="string"><span class="delimiter">&quot;</span><span class="content">volume_down</span><span class="delimiter">&quot;</span></span>
]
}
]
</pre></div>
</div>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">[</span><span class="w">
</span><span class="p">{</span><span class="w">
</span><span class="nt">"domain"</span><span class="p">:</span><span class="w"> </span><span class="s2">"browser"</span><span class="p">,</span><span class="w">
</span><span class="nt">"services"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w">
</span><span class="s2">"browse_url"</span><span class="w">
</span><span class="p">]</span><span class="w">
</span><span class="p">},</span><span class="w">
</span><span class="p">{</span><span class="w">
</span><span class="nt">"domain"</span><span class="p">:</span><span class="w"> </span><span class="s2">"keyboard"</span><span class="p">,</span><span class="w">
</span><span class="nt">"services"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w">
</span><span class="s2">"volume_up"</span><span class="p">,</span><span class="w">
</span><span class="s2">"volume_down"</span><span class="w">
</span><span class="p">]</span><span class="w">
</span><span class="p">}</span><span class="w">
</span><span class="p">]</span><span class="w">
</span></code></pre>
</div>
<p>Sample <code>curl</code> command:</p>
<p>Sample <code class="highlighter-rouge">curl</code> command:</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>$ curl -X GET -H &quot;x-ha-access: YOUR_PASSWORD&quot; \
-H &quot;Content-Type: application/json&quot; http://localhost:8123/api/services
</pre></div>
</div>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>curl -X GET -H <span class="s2">"x-ha-access: YOUR_PASSWORD"</span> <span class="se">\</span>
-H <span class="s2">"Content-Type: application/json"</span> http://localhost:8123/api/services
</code></pre>
</div>
<h4><a class="title-link" name="get-apihistory" href="#get-apihistory"></a> GET /api/history</h4>
<p>Returns an array of state changes in the past. Each object contains further detail for the entities.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>[
[
{
<span class="key"><span class="delimiter">&quot;</span><span class="content">attributes</span><span class="delimiter">&quot;</span></span>: {
<span class="key"><span class="delimiter">&quot;</span><span class="content">friendly_name</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">Weather Temperature</span><span class="delimiter">&quot;</span></span>,
<span class="key"><span class="delimiter">&quot;</span><span class="content">unit_of_measurement</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="char">\u00b0</span><span class="content">C</span><span class="delimiter">&quot;</span></span>
},
<span class="key"><span class="delimiter">&quot;</span><span class="content">entity_id</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">sensor.weather_temperature</span><span class="delimiter">&quot;</span></span>,
<span class="key"><span class="delimiter">&quot;</span><span class="content">last_changed</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">2016-02-06T22:15:00+00:00</span><span class="delimiter">&quot;</span></span>,
<span class="key"><span class="delimiter">&quot;</span><span class="content">last_updated</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">2016-02-06T22:15:00+00:00</span><span class="delimiter">&quot;</span></span><span class="string"><span class="delimiter">&quot;</span><span class="content">,
</span><span class="delimiter">&quot;</span></span><span class="error">s</span><span class="error">t</span><span class="error">a</span><span class="error">t</span><span class="error">e</span><span class="string"><span class="delimiter">&quot;</span><span class="content">: </span><span class="delimiter">&quot;</span></span><span class="float">-3.9</span><span class="string"><span class="delimiter">&quot;</span><span class="content">
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">[</span><span class="w">
</span><span class="p">[</span><span class="w">
</span><span class="p">{</span><span class="w">
</span><span class="nt">"attributes"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
</span><span class="nt">"friendly_name"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Weather Temperature"</span><span class="p">,</span><span class="w">
</span><span class="nt">"unit_of_measurement"</span><span class="p">:</span><span class="w"> </span><span class="s2">"\u00b0C"</span><span class="w">
</span><span class="p">},</span><span class="w">
</span><span class="nt">"entity_id"</span><span class="p">:</span><span class="w"> </span><span class="s2">"sensor.weather_temperature"</span><span class="p">,</span><span class="w">
</span><span class="nt">"last_changed"</span><span class="p">:</span><span class="w"> </span><span class="s2">"2016-02-06T22:15:00+00:00"</span><span class="p">,</span><span class="w">
</span><span class="nt">"last_updated"</span><span class="p">:</span><span class="w"> </span><span class="s2">"2016-02-06T22:15:00+00:00"",
"</span><span class="err">state</span><span class="s2">": "</span><span class="mf">-3.9</span><span class="s2">"
},
{
</span><span class="delimiter">&quot;</span></span><span class="error">a</span><span class="error">t</span><span class="error">t</span><span class="error">r</span><span class="error">i</span><span class="error">b</span><span class="error">u</span><span class="error">t</span><span class="error">e</span><span class="error">s</span><span class="string"><span class="delimiter">&quot;</span><span class="content">: {
</span><span class="delimiter">&quot;</span></span><span class="error">f</span><span class="error">r</span><span class="error">i</span><span class="error">e</span><span class="error">n</span><span class="error">d</span><span class="error">l</span><span class="error">y</span><span class="error">_</span><span class="error">n</span><span class="error">a</span><span class="error">m</span><span class="error">e</span><span class="string"><span class="delimiter">&quot;</span><span class="content">: </span><span class="delimiter">&quot;</span></span><span class="error">W</span><span class="error">e</span><span class="error">a</span><span class="error">t</span><span class="error">h</span><span class="error">e</span><span class="error">r</span> <span class="error">T</span><span class="error">e</span><span class="error">m</span><span class="error">p</span><span class="error">e</span><span class="error">r</span><span class="error">a</span><span class="error">t</span><span class="error">u</span><span class="error">r</span><span class="error">e</span><span class="string"><span class="delimiter">&quot;</span><span class="content">,
</span><span class="delimiter">&quot;</span></span><span class="error">u</span><span class="error">n</span><span class="error">i</span><span class="error">t</span><span class="error">_</span><span class="error">o</span><span class="error">f</span><span class="error">_</span><span class="error">m</span><span class="error">e</span><span class="error">a</span><span class="error">s</span><span class="error">u</span><span class="error">r</span><span class="error">e</span><span class="error">m</span><span class="error">e</span><span class="error">n</span><span class="error">t</span><span class="string"><span class="delimiter">&quot;</span><span class="content">: </span><span class="delimiter">&quot;</span></span><span class="error">\</span><span class="error">u</span><span class="integer">0</span><span class="integer">0</span><span class="error">b</span><span class="integer">0</span><span class="error">C</span><span class="string"><span class="delimiter">&quot;</span><span class="content">
"</span><span class="err">attributes</span><span class="s2">": {
"</span><span class="err">friendly_name</span><span class="s2">": "</span><span class="err">Weather</span><span class="w"> </span><span class="err">Temperature</span><span class="s2">",
"</span><span class="err">unit_of_measurement</span><span class="s2">": "</span><span class="err">\u</span><span class="mi">00</span><span class="err">b</span><span class="mi">0</span><span class="err">C</span><span class="s2">"
},
</span><span class="delimiter">&quot;</span></span><span class="error">e</span><span class="error">n</span><span class="error">t</span><span class="error">i</span><span class="error">t</span><span class="error">y</span><span class="error">_</span><span class="error">i</span><span class="error">d</span><span class="string"><span class="delimiter">&quot;</span><span class="content">: </span><span class="delimiter">&quot;</span></span><span class="error">s</span><span class="error">e</span><span class="error">n</span><span class="error">s</span><span class="error">o</span><span class="error">r</span><span class="error">.</span><span class="error">w</span><span class="error">e</span><span class="error">a</span><span class="error">t</span><span class="error">h</span><span class="error">e</span><span class="error">r</span><span class="error">_</span><span class="error">t</span><span class="error">e</span><span class="error">m</span><span class="error">p</span><span class="error">e</span><span class="error">r</span><span class="error">a</span><span class="error">t</span><span class="error">u</span><span class="error">r</span><span class="error">e</span><span class="string"><span class="delimiter">&quot;</span><span class="content">,
</span><span class="delimiter">&quot;</span></span><span class="error">l</span><span class="error">a</span><span class="error">s</span><span class="error">t</span><span class="error">_</span><span class="error">c</span><span class="error">h</span><span class="error">a</span><span class="error">n</span><span class="error">g</span><span class="error">e</span><span class="error">d</span><span class="string"><span class="delimiter">&quot;</span><span class="content">: </span><span class="delimiter">&quot;</span></span><span class="integer">2016</span><span class="integer">-0</span><span class="integer">2</span><span class="integer">-0</span><span class="integer">6</span><span class="error">T</span><span class="integer">22</span>:<span class="integer">15</span>:<span class="integer">0</span><span class="integer">0</span><span class="error">+</span><span class="integer">0</span><span class="integer">0</span>:<span class="integer">0</span><span class="integer">0</span><span class="string"><span class="delimiter">&quot;</span><span class="delimiter">&quot;</span></span>,
<span class="key"><span class="delimiter">&quot;</span><span class="content">last_updated</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">2016-02-06T22:15:00+00:00</span><span class="delimiter">&quot;</span></span><span class="string"><span class="delimiter">&quot;</span><span class="content">,
</span><span class="delimiter">&quot;</span></span><span class="error">s</span><span class="error">t</span><span class="error">a</span><span class="error">t</span><span class="error">e</span><span class="string"><span class="delimiter">&quot;</span><span class="content">: </span><span class="delimiter">&quot;</span></span><span class="float">-1.9</span><span class="string"><span class="delimiter">&quot;</span><span class="content">
},
]
]
</span></span></pre></div>
</div>
"</span><span class="err">entity_id</span><span class="s2">": "</span><span class="err">sensor.weather_temperature</span><span class="s2">",
"</span><span class="err">last_changed</span><span class="s2">": "</span><span class="mi">2016-02-06</span><span class="err">T</span><span class="mi">22</span><span class="err">:</span><span class="mi">15</span><span class="err">:</span><span class="mi">00</span><span class="err">+</span><span class="mi">00</span><span class="err">:</span><span class="mi">00</span><span class="s2">""</span><span class="p">,</span><span class="w">
</span><span class="nt">"last_updated"</span><span class="p">:</span><span class="w"> </span><span class="s2">"2016-02-06T22:15:00+00:00"",
"</span><span class="err">state</span><span class="s2">": "</span><span class="mf">-1.9</span><span class="err">"</span><span class="w">
</span><span class="p">},</span><span class="w">
</span><span class="p">]</span><span class="w">
</span><span class="p">]</span><span class="w">
</span></code></pre>
</div>
<p>Sample <code>curl</code> commands:</p>
<p>Sample <code class="highlighter-rouge">curl</code> commands:</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>$ curl -X GET -H &quot;x-ha-access: YOUR_PASSWORD&quot; \
-H &quot;Content-Type: application/json&quot; \
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>curl -X GET -H <span class="s2">"x-ha-access: YOUR_PASSWORD"</span> <span class="se">\</span>
-H <span class="s2">"Content-Type: application/json"</span> <span class="se">\</span>
http://localhost:8123/api/history/period/2016-02-06
</pre></div>
</div>
</code></pre>
</div>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>$ curl -X GET -H &quot;x-ha-access: YOUR_PASSWORD&quot; \
-H &quot;Content-Type: application/json&quot; \
http://localhost:8123/api/history/period/2016-02-06?filter_entity_id=sensor.temperature
</pre></div>
</div>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>curl -X GET -H <span class="s2">"x-ha-access: YOUR_PASSWORD"</span> <span class="se">\</span>
-H <span class="s2">"Content-Type: application/json"</span> <span class="se">\</span>
http://localhost:8123/api/history/period/2016-02-06?filter_entity_id<span class="o">=</span>sensor.temperature
</code></pre>
</div>
<h4><a class="title-link" name="get-apistates" href="#get-apistates"></a> GET /api/states</h4>
<p>Returns an array of state objects. Each state has the following attributes: entity_id, state, last_changed and attributes.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>[
{
<span class="key"><span class="delimiter">&quot;</span><span class="content">attributes</span><span class="delimiter">&quot;</span></span>: {},
<span class="key"><span class="delimiter">&quot;</span><span class="content">entity_id</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">sun.sun</span><span class="delimiter">&quot;</span></span>,
<span class="key"><span class="delimiter">&quot;</span><span class="content">last_changed</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">2016-05-30T21:43:32.418320+00:00</span><span class="delimiter">&quot;</span></span>,
<span class="key"><span class="delimiter">&quot;</span><span class="content">state</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">below_horizon</span><span class="delimiter">&quot;</span></span>
},
{
<span class="key"><span class="delimiter">&quot;</span><span class="content">attributes</span><span class="delimiter">&quot;</span></span>: {},
<span class="key"><span class="delimiter">&quot;</span><span class="content">entity_id</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">process.Dropbox</span><span class="delimiter">&quot;</span></span>,
<span class="key"><span class="delimiter">&quot;</span><span class="content">last_changed</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">22016-05-30T21:43:32.418320+00:00</span><span class="delimiter">&quot;</span></span>,
<span class="key"><span class="delimiter">&quot;</span><span class="content">state</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">on</span><span class="delimiter">&quot;</span></span>
}
]
</pre></div>
</div>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">[</span><span class="w">
</span><span class="p">{</span><span class="w">
</span><span class="nt">"attributes"</span><span class="p">:</span><span class="w"> </span><span class="p">{},</span><span class="w">
</span><span class="nt">"entity_id"</span><span class="p">:</span><span class="w"> </span><span class="s2">"sun.sun"</span><span class="p">,</span><span class="w">
</span><span class="nt">"last_changed"</span><span class="p">:</span><span class="w"> </span><span class="s2">"2016-05-30T21:43:32.418320+00:00"</span><span class="p">,</span><span class="w">
</span><span class="nt">"state"</span><span class="p">:</span><span class="w"> </span><span class="s2">"below_horizon"</span><span class="w">
</span><span class="p">},</span><span class="w">
</span><span class="p">{</span><span class="w">
</span><span class="nt">"attributes"</span><span class="p">:</span><span class="w"> </span><span class="p">{},</span><span class="w">
</span><span class="nt">"entity_id"</span><span class="p">:</span><span class="w"> </span><span class="s2">"process.Dropbox"</span><span class="p">,</span><span class="w">
</span><span class="nt">"last_changed"</span><span class="p">:</span><span class="w"> </span><span class="s2">"22016-05-30T21:43:32.418320+00:00"</span><span class="p">,</span><span class="w">
</span><span class="nt">"state"</span><span class="p">:</span><span class="w"> </span><span class="s2">"on"</span><span class="w">
</span><span class="p">}</span><span class="w">
</span><span class="p">]</span><span class="w">
</span></code></pre>
</div>
<p>Sample <code>curl</code> command:</p>
<p>Sample <code class="highlighter-rouge">curl</code> command:</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>$ curl -X GET -H &quot;x-ha-access: YOUR_PASSWORD&quot; \
-H &quot;Content-Type: application/json&quot; http://localhost:8123/api/states
</pre></div>
</div>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>curl -X GET -H <span class="s2">"x-ha-access: YOUR_PASSWORD"</span> <span class="se">\</span>
-H <span class="s2">"Content-Type: application/json"</span> http://localhost:8123/api/states
</code></pre>
</div>
<h4><a class="title-link" name="get-apistatesltentity_id" href="#get-apistatesltentity_id"></a> GET /api/states/&lt;entity_id&gt;</h4>
<p>Returns a state object for specified entity_id. Returns 404 if not found.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>{
<span class="key"><span class="delimiter">&quot;</span><span class="content">attributes</span><span class="delimiter">&quot;</span></span>:{
<span class="key"><span class="delimiter">&quot;</span><span class="content">azimuth</span><span class="delimiter">&quot;</span></span>:<span class="float">336.34</span>,
<span class="key"><span class="delimiter">&quot;</span><span class="content">elevation</span><span class="delimiter">&quot;</span></span>:<span class="float">-17.67</span>,
<span class="key"><span class="delimiter">&quot;</span><span class="content">friendly_name</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">Sun</span><span class="delimiter">&quot;</span></span>,
<span class="key"><span class="delimiter">&quot;</span><span class="content">next_rising</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">2016-05-31T03:39:14+00:00</span><span class="delimiter">&quot;</span></span>,
<span class="key"><span class="delimiter">&quot;</span><span class="content">next_setting</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">2016-05-31T19:16:42+00:00</span><span class="delimiter">&quot;</span></span>
},
<span class="key"><span class="delimiter">&quot;</span><span class="content">entity_id</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">sun.sun</span><span class="delimiter">&quot;</span></span>,
<span class="key"><span class="delimiter">&quot;</span><span class="content">last_changed</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">2016-05-30T21:43:29.204838+00:00</span><span class="delimiter">&quot;</span></span>,
<span class="key"><span class="delimiter">&quot;</span><span class="content">last_updated</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">2016-05-30T21:50:30.529465+00:00</span><span class="delimiter">&quot;</span></span>,
<span class="key"><span class="delimiter">&quot;</span><span class="content">state</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">below_horizon</span><span class="delimiter">&quot;</span></span>
}
</pre></div>
</div>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"attributes"</span><span class="p">:{</span><span class="w">
</span><span class="nt">"azimuth"</span><span class="p">:</span><span class="mf">336.34</span><span class="p">,</span><span class="w">
</span><span class="nt">"elevation"</span><span class="p">:</span><span class="mf">-17.67</span><span class="p">,</span><span class="w">
</span><span class="nt">"friendly_name"</span><span class="p">:</span><span class="s2">"Sun"</span><span class="p">,</span><span class="w">
</span><span class="nt">"next_rising"</span><span class="p">:</span><span class="s2">"2016-05-31T03:39:14+00:00"</span><span class="p">,</span><span class="w">
</span><span class="nt">"next_setting"</span><span class="p">:</span><span class="s2">"2016-05-31T19:16:42+00:00"</span><span class="w">
</span><span class="p">},</span><span class="w">
</span><span class="nt">"entity_id"</span><span class="p">:</span><span class="s2">"sun.sun"</span><span class="p">,</span><span class="w">
</span><span class="nt">"last_changed"</span><span class="p">:</span><span class="s2">"2016-05-30T21:43:29.204838+00:00"</span><span class="p">,</span><span class="w">
</span><span class="nt">"last_updated"</span><span class="p">:</span><span class="s2">"2016-05-30T21:50:30.529465+00:00"</span><span class="p">,</span><span class="w">
</span><span class="nt">"state"</span><span class="p">:</span><span class="s2">"below_horizon"</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<p>Sample <code>curl</code> command:</p>
<p>Sample <code class="highlighter-rouge">curl</code> command:</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>$ curl -X GET -H &quot;x-ha-access: YOUR_PASSWORD&quot; \
-H &quot;Content-Type: application/json&quot; \
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>curl -X GET -H <span class="s2">"x-ha-access: YOUR_PASSWORD"</span> <span class="se">\</span>
-H <span class="s2">"Content-Type: application/json"</span> <span class="se">\</span>
http://localhost:8123/api/states/sensor.kitchen_temperature
</pre></div>
</div>
</code></pre>
</div>
<h4><a class="title-link" name="get-apierror_log" href="#get-apierror_log"></a> GET /api/error_log</h4>
<p>Retrieve all errors logged during the current session of Home Assistant as a plaintext response.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>15-12-20 11:02:50 homeassistant.components.recorder: Found unfinished sessions
<div class="language-text highlighter-rouge"><pre class="highlight"><code>15-12-20 11:02:50 homeassistant.components.recorder: Found unfinished sessions
15-12-20 11:03:03 netdisco.ssdp: Error fetching description at http://192.168.1.1:8200/rootDesc.xml
15-12-20 11:04:36 homeassistant.components.alexa: Received unknown intent HelpIntent
</pre></div>
</div>
</code></pre>
</div>
<p>Sample <code>curl</code> command:</p>
<p>Sample <code class="highlighter-rouge">curl</code> command:</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>$ curl -X GET -H &quot;x-ha-access: YOUR_PASSWORD&quot; \
-H &quot;Content-Type: application/json&quot; \
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>curl -X GET -H <span class="s2">"x-ha-access: YOUR_PASSWORD"</span> <span class="se">\</span>
-H <span class="s2">"Content-Type: application/json"</span> <span class="se">\</span>
http://localhost:8123/api/error_log
</pre></div>
</div>
</code></pre>
</div>
<h4><a class="title-link" name="get-apicamera_proxycameraltentity_id" href="#get-apicamera_proxycameraltentity_id"></a> GET /api/camera_proxy/camera.&lt;entity_id&gt;</h4>
<p>Returns the data (image) from the specified camera entity_id.</p>
<p>Sample <code>curl</code> command:</p>
<p>Sample <code class="highlighter-rouge">curl</code> command:</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>$ curl -X GET -H &quot;x-ha-access: YOUR_PASSWORD&quot; \
-H &quot;Content-Type: application/json&quot; \
http://localhost:8123/api/camera_proxy/camera.my_sample_camera?time=1462653861261 -o image.jpg
</pre></div>
</div>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>curl -X GET -H <span class="s2">"x-ha-access: YOUR_PASSWORD"</span> <span class="se">\</span>
-H <span class="s2">"Content-Type: application/json"</span> <span class="se">\</span>
http://localhost:8123/api/camera_proxy/camera.my_sample_camera?time<span class="o">=</span>1462653861261 -o image.jpg
</code></pre>
</div>
<h4><a class="title-link" name="post-apistatesltentity_id" href="#post-apistatesltentity_id"></a> POST /api/states/&lt;entity_id&gt;</h4>
@ -454,112 +406,96 @@ You can append <code>?password=YOUR_PASSWORD</code> to any url to log in automat
<p>Expects a JSON object that has at least a state attribute:</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>{
<span class="key"><span class="delimiter">&quot;</span><span class="content">state</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">below_horizon</span><span class="delimiter">&quot;</span></span>,
<span class="key"><span class="delimiter">&quot;</span><span class="content">attributes</span><span class="delimiter">&quot;</span></span>: {
<span class="key"><span class="delimiter">&quot;</span><span class="content">next_rising</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">2016-05-31T03:39:14+00:00</span><span class="delimiter">&quot;</span></span>,
<span class="key"><span class="delimiter">&quot;</span><span class="content">next_setting</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">2016-05-31T19:16:42+00:00</span><span class="delimiter">&quot;</span></span>
}
}
</pre></div>
</div>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"state"</span><span class="p">:</span><span class="w"> </span><span class="s2">"below_horizon"</span><span class="p">,</span><span class="w">
</span><span class="nt">"attributes"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
</span><span class="nt">"next_rising"</span><span class="p">:</span><span class="s2">"2016-05-31T03:39:14+00:00"</span><span class="p">,</span><span class="w">
</span><span class="nt">"next_setting"</span><span class="p">:</span><span class="s2">"2016-05-31T19:16:42+00:00"</span><span class="w">
</span><span class="p">}</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<p>Return code is 200 if the entity existed, 201 if the state of a new entity was set. A location header will be returned with the url of the new resource. The response body will contain a JSON encoded State object.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>{
<span class="key"><span class="delimiter">&quot;</span><span class="content">attributes</span><span class="delimiter">&quot;</span></span>: {
<span class="key"><span class="delimiter">&quot;</span><span class="content">next_rising</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">2016-05-31T03:39:14+00:00</span><span class="delimiter">&quot;</span></span>,
<span class="key"><span class="delimiter">&quot;</span><span class="content">next_setting</span><span class="delimiter">&quot;</span></span>:<span class="string"><span class="delimiter">&quot;</span><span class="content">2016-05-31T19:16:42+00:00</span><span class="delimiter">&quot;</span></span>
},
<span class="key"><span class="delimiter">&quot;</span><span class="content">entity_id</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">sun.sun</span><span class="delimiter">&quot;</span></span>,
<span class="key"><span class="delimiter">&quot;</span><span class="content">last_changed</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">2016-05-30T21:43:29.204838+00:00</span><span class="delimiter">&quot;</span></span>,
<span class="key"><span class="delimiter">&quot;</span><span class="content">last_updated</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">2016-05-30T21:47:30.533530+00:00</span><span class="delimiter">&quot;</span></span>
<span class="key"><span class="delimiter">&quot;</span><span class="content">state</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">below_horizon</span><span class="delimiter">&quot;</span></span>
}
</pre></div>
</div>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"attributes"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
</span><span class="nt">"next_rising"</span><span class="p">:</span><span class="s2">"2016-05-31T03:39:14+00:00"</span><span class="p">,</span><span class="w">
</span><span class="nt">"next_setting"</span><span class="p">:</span><span class="s2">"2016-05-31T19:16:42+00:00"</span><span class="w">
</span><span class="p">},</span><span class="w">
</span><span class="nt">"entity_id"</span><span class="p">:</span><span class="w"> </span><span class="s2">"sun.sun"</span><span class="p">,</span><span class="w">
</span><span class="nt">"last_changed"</span><span class="p">:</span><span class="w"> </span><span class="s2">"2016-05-30T21:43:29.204838+00:00"</span><span class="p">,</span><span class="w">
</span><span class="nt">"last_updated"</span><span class="p">:</span><span class="w"> </span><span class="s2">"2016-05-30T21:47:30.533530+00:00"</span><span class="w">
</span><span class="s2">"state"</span><span class="err">:</span><span class="w"> </span><span class="s2">"below_horizon"</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<p>Sample <code>curl</code> command:</p>
<p>Sample <code class="highlighter-rouge">curl</code> command:</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>$ curl -X POST -H &quot;x-ha-access: YOUR_PASSWORD&quot; \
-H &quot;Content-Type: application/json&quot; \
-d '{&quot;state&quot;: &quot;25&quot;, &quot;attributes&quot;: {&quot;unit_of_measurement&quot;: &quot;°C&quot;}}' \
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>curl -X POST -H <span class="s2">"x-ha-access: YOUR_PASSWORD"</span> <span class="se">\</span>
-H <span class="s2">"Content-Type: application/json"</span> <span class="se">\</span>
-d <span class="s1">'{"state": "25", "attributes": {"unit_of_measurement": "°C"}}'</span> <span class="se">\</span>
http://localhost:8123/api/states/sensor.kitchen_temperature
</pre></div>
</div>
</code></pre>
</div>
<h4><a class="title-link" name="post-apieventsltevent_type" href="#post-apieventsltevent_type"></a> POST /api/events/&lt;event_type&gt;</h4>
<p>Fires an event with event_type</p>
<p>You can pass an optional JSON object to be used as <code>event_data</code>.</p>
<p>You can pass an optional JSON object to be used as <code class="highlighter-rouge">event_data</code>.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>{
<span class="error">n</span><span class="error">e</span><span class="error">x</span><span class="error">t</span><span class="error">_</span><span class="error">r</span><span class="error">i</span><span class="error">s</span><span class="error">i</span><span class="error">n</span><span class="error">g</span><span class="string"><span class="delimiter">&quot;</span><span class="content">:</span><span class="delimiter">&quot;</span></span><span class="integer">2016</span><span class="integer">-0</span><span class="integer">5</span><span class="integer">-31</span><span class="error">T</span><span class="integer">0</span><span class="integer">3</span>:<span class="integer">39</span>:<span class="integer">14</span><span class="error">+</span><span class="integer">0</span><span class="integer">0</span>:<span class="integer">0</span><span class="integer">0</span><span class="string"><span class="delimiter">&quot;</span><span class="content">,
}
</span></span></pre></div>
</div>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="err">next_rising</span><span class="nt">":"</span><span class="err">2016-05-31T03</span><span class="p">:</span><span class="mi">39</span><span class="err">:</span><span class="mi">14</span><span class="err">+</span><span class="mi">00</span><span class="err">:</span><span class="mi">00</span><span class="err">"</span><span class="p">,</span><span class="w">
</span><span class="err">}</span><span class="w">
</span></code></pre>
</div>
<p>Returns a message if successful.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>{
<span class="key"><span class="delimiter">&quot;</span><span class="content">message</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">Event download_file fired.</span><span class="delimiter">&quot;</span></span>
}
</pre></div>
</div>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"message"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Event download_file fired."</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<h4><a class="title-link" name="post-apiservicesltdomainltservice" href="#post-apiservicesltdomainltservice"></a> POST /api/services/&lt;domain&gt;/&lt;service&gt;</h4>
<p>Calls a service within a specific domain. Will return when the service has been executed or 10 seconds has past, whichever comes first.</p>
<p>You can pass an optional JSON object to be used as <code>service_data</code>.</p>
<p>You can pass an optional JSON object to be used as <code class="highlighter-rouge">service_data</code>.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>{
<span class="key"><span class="delimiter">&quot;</span><span class="content">entity_id</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">light.Ceiling</span><span class="delimiter">&quot;</span></span>
}
</pre></div>
</div>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"entity_id"</span><span class="p">:</span><span class="w"> </span><span class="s2">"light.Ceiling"</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<p>Returns a list of states that have changed while the service was being executed.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>[
{
<span class="key"><span class="delimiter">&quot;</span><span class="content">attributes</span><span class="delimiter">&quot;</span></span>: {},
<span class="key"><span class="delimiter">&quot;</span><span class="content">entity_id</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">sun.sun</span><span class="delimiter">&quot;</span></span>,
<span class="key"><span class="delimiter">&quot;</span><span class="content">last_changed</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">2016-05-30T21:43:32.418320+00:00</span><span class="delimiter">&quot;</span></span>,
<span class="key"><span class="delimiter">&quot;</span><span class="content">state</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">below_horizon</span><span class="delimiter">&quot;</span></span>
},
{
<span class="key"><span class="delimiter">&quot;</span><span class="content">attributes</span><span class="delimiter">&quot;</span></span>: {},
<span class="key"><span class="delimiter">&quot;</span><span class="content">entity_id</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">process.Dropbox</span><span class="delimiter">&quot;</span></span>,
<span class="key"><span class="delimiter">&quot;</span><span class="content">last_changed</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">22016-05-30T21:43:32.418320+00:00</span><span class="delimiter">&quot;</span></span>,
<span class="key"><span class="delimiter">&quot;</span><span class="content">state</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">on</span><span class="delimiter">&quot;</span></span>
}
]
</pre></div>
</div>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">[</span><span class="w">
</span><span class="p">{</span><span class="w">
</span><span class="nt">"attributes"</span><span class="p">:</span><span class="w"> </span><span class="p">{},</span><span class="w">
</span><span class="nt">"entity_id"</span><span class="p">:</span><span class="w"> </span><span class="s2">"sun.sun"</span><span class="p">,</span><span class="w">
</span><span class="nt">"last_changed"</span><span class="p">:</span><span class="w"> </span><span class="s2">"2016-05-30T21:43:32.418320+00:00"</span><span class="p">,</span><span class="w">
</span><span class="nt">"state"</span><span class="p">:</span><span class="w"> </span><span class="s2">"below_horizon"</span><span class="w">
</span><span class="p">},</span><span class="w">
</span><span class="p">{</span><span class="w">
</span><span class="nt">"attributes"</span><span class="p">:</span><span class="w"> </span><span class="p">{},</span><span class="w">
</span><span class="nt">"entity_id"</span><span class="p">:</span><span class="w"> </span><span class="s2">"process.Dropbox"</span><span class="p">,</span><span class="w">
</span><span class="nt">"last_changed"</span><span class="p">:</span><span class="w"> </span><span class="s2">"22016-05-30T21:43:32.418320+00:00"</span><span class="p">,</span><span class="w">
</span><span class="nt">"state"</span><span class="p">:</span><span class="w"> </span><span class="s2">"on"</span><span class="w">
</span><span class="p">}</span><span class="w">
</span><span class="p">]</span><span class="w">
</span></code></pre>
</div>
<p>Sample <code>curl</code> command:</p>
<p>Sample <code class="highlighter-rouge">curl</code> command:</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>$ curl -X POST -H &quot;x-ha-access: YOUR_PASSWORD&quot; \
-H &quot;Content-Type: application/json&quot; \
-d '{&quot;entity_id&quot;: &quot;switch.christmas_lights&quot;, &quot;state&quot;: &quot;on&quot;}' \
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>curl -X POST -H <span class="s2">"x-ha-access: YOUR_PASSWORD"</span> <span class="se">\</span>
-H <span class="s2">"Content-Type: application/json"</span> <span class="se">\</span>
-d <span class="s1">'{"entity_id": "switch.christmas_lights", "state": "on"}'</span> <span class="se">\</span>
http://localhost:8123/api/services/switch/turn_on
</pre></div>
</div>
</code></pre>
</div>
<p class="note">
@ -569,30 +505,24 @@ The result will include any changed states that changed while the service was be
<h4><a class="title-link" name="post-apitemplate" href="#post-apitemplate"></a> POST /api/template</h4>
<p>Render a Home Assistant template. <a href="/topics/templating/">See template docs for more information.</a></p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>{
<span class="key"><span class="delimiter">&quot;</span><span class="content">template</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">Paulus is at {{ states('device_tracker.paulus') }}!</span><span class="delimiter">&quot;</span></span>
}
</pre></div>
</div>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"template"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Paulus is at {{ states('device_tracker.paulus') }}!"</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<p>Returns the rendered template in plain text.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>Paulus is at work!
</pre></div>
</div>
<div class="language-text highlighter-rouge"><pre class="highlight"><code>Paulus is at work!
</code></pre>
</div>
<p>Sample <code>curl</code> command:</p>
<p>Sample <code class="highlighter-rouge">curl</code> command:</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>$ curl -X POST -H &quot;x-ha-access: YOUR_PASSWORD&quot; \
-H &quot;Content-Type: application/json&quot; \
-d '{&quot;template&quot;: &quot;It is !&quot;}' http://localhost:8123/api/template
</pre></div>
</div>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>curl -X POST -H <span class="s2">"x-ha-access: YOUR_PASSWORD"</span> <span class="se">\</span>
-H <span class="s2">"Content-Type: application/json"</span> <span class="se">\</span>
-d <span class="s1">'{"template": "It is !"}'</span> http://localhost:8123/api/template
</code></pre>
</div>
<h4><a class="title-link" name="post-apievent_forwarding" href="#post-apievent_forwarding"></a> POST /api/event_forwarding</h4>
@ -600,24 +530,20 @@ The result will include any changed states that changed while the service was be
<p>Requires a JSON object that represents the API to forward to.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>{
<span class="key"><span class="delimiter">&quot;</span><span class="content">host</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">machine</span><span class="delimiter">&quot;</span></span>,
<span class="key"><span class="delimiter">&quot;</span><span class="content">api_password</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">my_super_secret_password</span><span class="delimiter">&quot;</span></span>,
<span class="key"><span class="delimiter">&quot;</span><span class="content">port</span><span class="delimiter">&quot;</span></span>: <span class="integer">8880</span> <span class="error">/</span><span class="error">/</span> <span class="error">o</span><span class="error">p</span><span class="error">t</span><span class="error">i</span><span class="error">o</span><span class="error">n</span><span class="error">a</span><span class="error">l</span>
}
</pre></div>
</div>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"host"</span><span class="p">:</span><span class="w"> </span><span class="s2">"machine"</span><span class="p">,</span><span class="w">
</span><span class="nt">"api_password"</span><span class="p">:</span><span class="w"> </span><span class="s2">"my_super_secret_password"</span><span class="p">,</span><span class="w">
</span><span class="nt">"port"</span><span class="p">:</span><span class="w"> </span><span class="mi">8880</span><span class="w"> </span><span class="err">//</span><span class="w"> </span><span class="err">optional</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<p>It will return a message if event forwarding was setup successful.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>{
<span class="key"><span class="delimiter">&quot;</span><span class="content">message</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">Event forwarding setup.</span><span class="delimiter">&quot;</span></span>
}
</pre></div>
</div>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"message"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Event forwarding setup."</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<h4><a class="title-link" name="delete-apievent_forwarding" href="#delete-apievent_forwarding"></a> DELETE /api/event_forwarding</h4>
@ -625,24 +551,20 @@ The result will include any changed states that changed while the service was be
<p>Requires a JSON object that represents the API to cancel forwarding to.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>{
<span class="key"><span class="delimiter">&quot;</span><span class="content">host</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">machine</span><span class="delimiter">&quot;</span></span>,
<span class="key"><span class="delimiter">&quot;</span><span class="content">api_password</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">my_super_secret_password</span><span class="delimiter">&quot;</span></span>,
<span class="key"><span class="delimiter">&quot;</span><span class="content">port</span><span class="delimiter">&quot;</span></span>: <span class="integer">8880</span> <span class="error">/</span><span class="error">/</span> <span class="error">o</span><span class="error">p</span><span class="error">t</span><span class="error">i</span><span class="error">o</span><span class="error">n</span><span class="error">a</span><span class="error">l</span>
}
</pre></div>
</div>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"host"</span><span class="p">:</span><span class="w"> </span><span class="s2">"machine"</span><span class="p">,</span><span class="w">
</span><span class="nt">"api_password"</span><span class="p">:</span><span class="w"> </span><span class="s2">"my_super_secret_password"</span><span class="p">,</span><span class="w">
</span><span class="nt">"port"</span><span class="p">:</span><span class="w"> </span><span class="mi">8880</span><span class="w"> </span><span class="err">//</span><span class="w"> </span><span class="err">optional</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<p>It will return a message if event forwarding was cancelled successful.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>{
<span class="key"><span class="delimiter">&quot;</span><span class="content">message</span><span class="delimiter">&quot;</span></span>: <span class="string"><span class="delimiter">&quot;</span><span class="content">Event forwarding cancelled.</span><span class="delimiter">&quot;</span></span>
}
</pre></div>
</div>
<div class="language-json highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nt">"message"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Event forwarding cancelled."</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre>
</div>
<p class="note">

72
developers/server_sent_events/index.html
View file

@ -91,49 +91,43 @@
<p>The <a href="https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events">server-sent events</a> feature is a one-way channel from your Home Assistant server to a client which is acting as a consumer. For bi-directional communication check the <a href="/developers/rest_api/">RESTful API</a> and <a href="/developers/python_api/">Python API</a>.</p>
<p>The URI that is generating the data is <code>/api/stream</code>.</p>
<p>The URI that is generating the data is <code class="highlighter-rouge">/api/stream</code>.</p>
<p>A requirement on the client-side is existing support for the <a href="https://developer.mozilla.org/en-US/docs/Web/API/EventSource">EventSource</a> interface.</p>
<p>There are various ways to access the stream. One is <code>curl</code>:</p>
<p>There are various ways to access the stream. One is <code class="highlighter-rouge">curl</code>:</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>$ curl -X GET -H &quot;x-ha-access: YOUR_PASSWORD&quot; \
-H &quot;Content-Type: application/json&quot; http://localhost:8123/api/stream
</pre></div>
</div>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>curl -X GET -H <span class="s2">"x-ha-access: YOUR_PASSWORD"</span> <span class="se">\</span>
-H <span class="s2">"Content-Type: application/json"</span> http://localhost:8123/api/stream
</code></pre>
</div>
<p>For more comfort put the HTML snippet below in a file <code>sse.html</code> in your <code>www</code> folder of your Home Assistant configuration directory (<code>.homeassistant</code>)</p>
<p>For more comfort put the HTML snippet below in a file <code class="highlighter-rouge">sse.html</code> in your <code class="highlighter-rouge">www</code> folder of your Home Assistant configuration directory (<code class="highlighter-rouge">.homeassistant</code>)</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre><span class="doctype">&lt;!DOCTYPE html&gt;</span>
<span class="tag">&lt;html&gt;</span>
<span class="tag">&lt;body&gt;</span>
<span class="tag">&lt;h1&gt;</span>Getting Home Assistant server events<span class="tag">&lt;/h1&gt;</span>
<span class="tag">&lt;div</span> <span class="attribute-name">id</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">events</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span><span class="tag">&lt;/div&gt;</span>
<span class="tag">&lt;script</span> <span class="attribute-name">type</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">text/javascript</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
<span class="inline"> <span class="keyword">var</span> source = <span class="keyword">new</span> EventSource(<span class="string"><span class="delimiter">&quot;</span><span class="content">/api/stream?password=YOUR_PASSWORD</span><span class="delimiter">&quot;</span></span>);
source.<span class="function">onmessage</span> = <span class="keyword">function</span>(event) {
document.getElementById(<span class="string"><span class="delimiter">&quot;</span><span class="content">events</span><span class="delimiter">&quot;</span></span>).innerHTML += event.data + <span class="string"><span class="delimiter">&quot;</span><span class="content">&lt;br&gt;</span><span class="delimiter">&quot;</span></span>;
};</span>
<span class="tag">&lt;/script&gt;</span>
<span class="tag">&lt;/body&gt;</span>
<span class="tag">&lt;/html&gt;</span>
</pre></div>
</div>
<div class="language-html highlighter-rouge"><pre class="highlight"><code><span class="cp">&lt;!DOCTYPE html&gt;</span>
<span class="nt">&lt;html&gt;</span>
<span class="nt">&lt;body&gt;</span>
<span class="nt">&lt;h1&gt;</span>Getting Home Assistant server events<span class="nt">&lt;/h1&gt;</span>
<span class="nt">&lt;div</span> <span class="na">id=</span><span class="s">"events"</span><span class="nt">&gt;&lt;/div&gt;</span>
<span class="nt">&lt;script </span><span class="na">type=</span><span class="s">"text/javascript"</span><span class="nt">&gt;</span>
<span class="kd">var</span> <span class="nx">source</span> <span class="o">=</span> <span class="k">new</span> <span class="nx">EventSource</span><span class="p">(</span><span class="s2">"/api/stream?password=YOUR_PASSWORD"</span><span class="p">);</span>
<span class="nx">source</span><span class="p">.</span><span class="nx">onmessage</span> <span class="o">=</span> <span class="kd">function</span><span class="p">(</span><span class="nx">event</span><span class="p">)</span> <span class="p">{</span>
<span class="nb">document</span><span class="p">.</span><span class="nx">getElementById</span><span class="p">(</span><span class="s2">"events"</span><span class="p">).</span><span class="nx">innerHTML</span> <span class="o">+=</span> <span class="nx">event</span><span class="p">.</span><span class="nx">data</span> <span class="o">+</span> <span class="s2">"&lt;br&gt;"</span><span class="p">;</span>
<span class="p">};</span>
<span class="nt">&lt;/script&gt;</span>
<span class="nt">&lt;/body&gt;</span>
<span class="nt">&lt;/html&gt;</span>
</code></pre>
</div>
<p>Visit <a href="http://localhost:8123/local/sse.html">http://localhost:8123/local/sse.html</a> to see the stream of events.</p>
<h2><a class="title-link" name="examples" href="#examples"></a> Examples</h2>
<p>A simplest way to consume server-sent events is <code>httpie</code>.</p>
<p>A simplest way to consume server-sent events is <code class="highlighter-rouge">httpie</code>.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>$ http --stream http://localhost:8123/api/stream x-ha-access:YOUR_PASSWORD content-type:application/json
</pre></div>
</div>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>http --stream http://localhost:8123/api/stream x-ha-access:YOUR_PASSWORD content-type:application/json
</code></pre>
</div>
<h3><a class="title-link" name="website" href="#website"></a> Website</h3>
@ -142,24 +136,20 @@
<h3><a class="title-link" name="python" href="#python"></a> Python</h3>
<p>If you want test the server-sent events without creating a website then the Python module <a href="https://pypi.python.org/pypi/sseclient/"><code>sseclient</code> </a> can help. Install it first:</p>
<p>If you want test the server-sent events without creating a website then the Python module <a href="https://pypi.python.org/pypi/sseclient/"><code class="highlighter-rouge">sseclient</code> </a> can help. Install it first:</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>$ pip3 install sseclient
</pre></div>
</div>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>pip3 install sseclient
</code></pre>
</div>
<p>The simplest script to consume the SSE looks like the following snipplet.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre><span class="keyword">from</span> <span class="include">sseclient</span> <span class="keyword">import</span> <span class="include">SSEClient</span>
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="kn">from</span> <span class="nn">sseclient</span> <span class="kn">import</span> <span class="n">SSEClient</span>
messages = SSEClient(<span class="string"><span class="delimiter">'</span><span class="content">http://localhost:8123/api/stream?api_password=YOUR_PASSWORD</span><span class="delimiter">'</span></span>)
<span class="keyword">for</span> msg <span class="keyword">in</span> messages:
print(msg)
</pre></div>
</div>
<span class="n">messages</span> <span class="o">=</span> <span class="n">SSEClient</span><span class="p">(</span><span class="s">'http://localhost:8123/api/stream?api_password=YOUR_PASSWORD'</span><span class="p">)</span>
<span class="k">for</span> <span class="n">msg</span> <span class="ow">in</span> <span class="n">messages</span><span class="p">:</span>
<span class="k">print</span><span class="p">(</span><span class="n">msg</span><span class="p">)</span>
</code></pre>
</div>

23
developers/website/index.html
View file

@ -91,7 +91,7 @@
<p>The website you’re reading now is the home of Home Assistant: <a href="https://home-assistant.io">https://home-assistant.io</a>. This is the place where we provide documentation and additional details about Home Assistant for end users and developers.</p>
<p>home-assistant.io uses the <a href="http://octopress.org/">Octopress</a> framework for <a href="http://github.com/mojombo/jekyll">Jekyll</a>. To get more details, please checkout the <a href="http://octopress.org/docs/">Octopress documentation</a>.<br />
<p>home-assistant.io uses the <a href="http://octopress.org/">Octopress</a> framework for <a href="http://github.com/mojombo/jekyll">Jekyll</a>. To get more details, please checkout the <a href="http://octopress.org/docs/">Octopress documentation</a>.
That means that creating a new page is simple. The pages are written in <a href="http://daringfireball.net/projects/markdown/">markdown</a>; you don’t need to care about HTML or the like.</p>
<p>The process for working on the website is no different from working on Home Assistant itself.</p>
@ -100,16 +100,16 @@ That means that creating a new page is simple. The pages are written in <a href=
<ul>
<li><a href="https://www.ruby-lang.org/en/documentation/installation/">Install Ruby</a> if you don’t have it already.</li>
<li>Install <code>bundler</code>, which is a dependency manager for Ruby: <code>gem install bundler</code></li>
<li>In your home-assistant.io root directory, run <code>bundle</code> to install the gems you need.</li>
<li>Install <code class="highlighter-rouge">bundler</code>, which is a dependency manager for Ruby: <code class="highlighter-rouge">gem install bundler</code></li>
<li>In your home-assistant.io root directory, run <code class="highlighter-rouge">bundle</code> to install the gems you need.</li>
</ul>
<p>Then you can work on the documentation:</p>
<ul>
<li>Fork home-assistant.io <a href="https://github.com/home-assistant/home-assistant.github.io">git repository</a>.</li>
<li>Create/edit/update a page in the directory <code>source/_components/</code> for your platform/component.</li>
<li>Test your changes to home-assistant.io locally: run <code>rake preview</code> and navigate to <a href="http://127.0.0.1:4000">http://127.0.0.1:4000</a></li>
<li>Create/edit/update a page in the directory <code class="highlighter-rouge">source/_components/</code> for your platform/component.</li>
<li>Test your changes to home-assistant.io locally: run <code class="highlighter-rouge">rake preview</code> and navigate to <a href="http://127.0.0.1:4000">http://127.0.0.1:4000</a></li>
<li>Create a Pull Request (PR) against the <strong>next</strong> branch of home-assistant.io if your documentation is for a new feature, platform, or component.</li>
<li>Create a Pull Request (PR) against the <strong>current</strong> branch of home-assistant.io if you fix stuff, create Cookbook entries, or expand existing documentation.</li>
</ul>
@ -117,18 +117,17 @@ That means that creating a new page is simple. The pages are written in <a href=
<p>For a platform page, the fastest way is to make a copy of an existing page and edit it. The <a href="/components/">component overview</a> is generated automatically, so there is no need to add a link to your page.</p>
<h3><a class="title-link" name="code" href="#code"></a> Code</h3>
<p>To take advantage of the built-in features of Octopress to display code snippets, just use the default markdown syntax. Please use <code>$</code> and <code>#</code> if it’s a command and to differ from output.</p>
<p>To take advantage of the built-in features of Octopress to display code snippets, just use the default markdown syntax. Please use <code class="highlighter-rouge">$</code> and <code class="highlighter-rouge">#</code> if it’s a command and to differ from output.</p>
<div class="highlighter-coderay"><div class="CodeRay">
<div class="code"><pre>Here goes the code...
</pre></div>
</div>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code>Here goes the code...
</code></pre>
</div>
<p>If you want to display line numbers, add the following snippet somewhere on your page.</p>
<pre><code>{::options coderay_line_numbers="table" /}
</code></pre>
<div class="highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="err">::options</span><span class="w"> </span><span class="err">coderay_line_numbers=</span><span class="nt">"table"</span><span class="w"> </span><span class="err">/}</span><span class="w">
</span></code></pre>
</div>
<h3><a class="title-link" name="images-icons-and-logos" href="#images-icons-and-logos"></a> Images, icons, and logos</h3>
<p>The images which are displayed on the pages are stored in various directories according to their purpose.</p>