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

Site updated at 2018-01-28 22:02:31 UTC

Browse source
This commit is contained in:
Travis CI 2018-01-28 22:02:31 +00:00
parent 57a21e9eb0
commit 01b474f87c
268 changed files with 412 additions and 412 deletions
Download patch file Download diff file Expand all files Collapse all files

20
docs/ecosystem/appdaemon/api/index.html
View file

@ -83,11 +83,11 @@
<span class="k">class</span> <span class="nc">MotionLights</span><span class="p">(</span><span class="n">appapi</span><span class="o">.</span><span class="n">AppDaemon</span><span class="p">):</span>
</code></pre>
</div>
<p>When configured as an app in the config file (more on that later) the lifecycle of the App begins. It will be instantiated as an object by AppDaemon, and immediately, it will have a call made to it’s <code class="highlighter-rouge">initialize()</code> function - this function must appear as part of every app:</p>
<p>When configured as an app in the config file (more on that later) the lifecycle of the App begins. It will be instantiated as an object by AppDaemon, and immediately, it will have a call made to its <code class="highlighter-rouge">initialize()</code> function - this function must appear as part of every app:</p>
<div class="language-python highlighter-rouge"><pre class="highlight"><code> <span class="k">def</span> <span class="nf">initialize</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
</code></pre>
</div>
<p>The initialize function allows the app to register any callbacks it might need for responding to state changes, and also any setup activities. When the <code class="highlighter-rouge">initialize()</code> function returns, the App will be dormant until any of it’s callbacks are activated.</p>
<p>The initialize function allows the app to register any callbacks it might need for responding to state changes, and also any setup activities. When the <code class="highlighter-rouge">initialize()</code> function returns, the App will be dormant until any of its callbacks are activated.</p>
<p>There are several circumstances under which <code class="highlighter-rouge">initialize()</code> might be called:</p>
<ul>
<li>Initial start of AppDaemon</li>
@ -140,7 +140,7 @@
</code></pre>
</div>
<p>When AppDaemon sees the following configuration it will expect to find a class called <code class="highlighter-rouge">NewApp</code> defined in a module called <code class="highlighter-rouge">new.py</code> in the apps subdirectory. Apps can be placed at the root of the Apps directory or within a subdirectory, an arbitrary depth down - wherever the App is, as long as it is in some subdirectory of the Apps dir, or in the Apps dir itself, AppDaemon will find it. There is no need to include information about the path, just the name of the file itself (without the <code class="highlighter-rouge">.py</code>) is sufficient. If names in the subdirectories overlap, AppDir will pick one of them but the exact choice it will make is undefined.</p>
<p>When starting the system for the first time or when reloading an App or Module, the system will log the fact in it’s main log. It is often the case that there is a problem with the class, maybe a syntax error or some other problem. If that is the case, details will be output to the error log allowing the user to remedy the problem and reload.</p>
<p>When starting the system for the first time or when reloading an App or Module, the system will log the fact in its main log. It is often the case that there is a problem with the class, maybe a syntax error or some other problem. If that is the case, details will be output to the error log allowing the user to remedy the problem and reload.</p>
<h2><a class="title-link" name="steps-to-writing-an-app" href="#steps-to-writing-an-app"></a> Steps to writing an App</h2>
<ol>
<li>Create the code in a new or shared module by deriving a class from AppDaemon, add required callbacks and code</li>
@ -186,7 +186,7 @@
<h2><a class="title-link" name="callback-constraints" href="#callback-constraints"></a> Callback Constraints</h2>
<p>Callback constraints are a feature of AppDaemon that removes the need for repetition of some common coding checks. Many Apps will wish to process their callbacks only when certain conditions are met, e.g. someone is home, and it’s after sunset. These kinds of conditions crop up a lot, and use of callback constraints can significantly simplify the logic required within callbacks.</p>
<p>Put simply, callback constraints are one or more conditions on callback execution that can be applied to an individual App. An App’s callbacks will only be executed if all of the constraints are met. If a constraint is absent it will not be checked for.</p>
<p>For example, the presence callback constraint can be added to an App by adding a parameter to it’s configuration like this:</p>
<p>For example, the presence callback constraint can be added to an App by adding a parameter to its configuration like this:</p>
<div class="language-ini highlighter-rouge"><pre class="highlight"><code><span class="nn">[some_app]</span>
<span class="py">module</span> <span class="p">=</span> <span class="s">some_module</span>
<span class="py">class</span> <span class="p">=</span> <span class="s">SomeClass</span>
@ -476,7 +476,7 @@
</code></pre>
</div>
<h3><a class="title-link" name="info_listen_state" href="#info_listen_state"></a> info_listen_state()</h3>
<p>Get information on state a callback from it’s handle.</p>
<p>Get information on state a callback from its handle.</p>
<h4><a class="title-link" name="synopsis" href="#synopsis"></a> Synopsis</h4>
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="n">entity</span><span class="p">,</span> <span class="n">attribute</span><span class="p">,</span> <span class="n">kwargs</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">info_listen_state</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">handle</span><span class="p">)</span>
</code></pre>
@ -683,7 +683,7 @@
</code></pre>
</div>
<h3><a class="title-link" name="info_timer" href="#info_timer"></a> info_timer()</h3>
<p>Get information on a scheduler event from it’s handle.</p>
<p>Get information on a scheduler event from its handle.</p>
<h4><a class="title-link" name="synopsis" href="#synopsis"></a> Synopsis</h4>
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="n">time</span><span class="p">,</span> <span class="n">interval</span><span class="p">,</span> <span class="n">kwargs</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">info_timer</span><span class="p">(</span><span class="n">handle</span><span class="p">)</span>
</code></pre>
@ -705,7 +705,7 @@
<li><code class="highlighter-rouge">random_start</code> - start of range of the random time</li>
<li><code class="highlighter-rouge">random_end</code> - end of range of the random time</li>
</ul>
<p><code class="highlighter-rouge">random_start</code> must always be numerically lower than <code class="highlighter-rouge">random_end</code>, they can be negative to denote a random offset before and event, or positive to denote a random offset after an event. The event would be a an absolute or relative time or sunrise/sunset depending on which scheduler call you use and these values affect the base time by the spcified amount. If not specified, they will default to <code class="highlighter-rouge">0</code>.</p>
<p><code class="highlighter-rouge">random_start</code> must always be numerically lower than <code class="highlighter-rouge">random_end</code>, they can be negative to denote a random offset before and event, or positive to denote a random offset after an event. The event would be an absolute or relative time or sunrise/sunset depending on which scheduler call you use and these values affect the base time by the spcified amount. If not specified, they will default to <code class="highlighter-rouge">0</code>.</p>
<p>For example:</p>
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="c"># Run a callback in 2 minutes minus a random number of seconds between 0 and 60, e.g. run between 60 and 120 seconds from now</span>
<span class="bp">self</span><span class="o">.</span><span class="n">handle</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">run_in</span><span class="p">(</span><span class="n">callback</span><span class="p">,</span> <span class="mi">120</span><span class="p">,</span> <span class="n">random_start</span> <span class="o">=</span> <span class="o">-</span><span class="mi">60</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>
@ -1029,7 +1029,7 @@
</code></pre>
</div>
<h3><a class="title-link" name="info_listen_event" href="#info_listen_event"></a> info_listen_event()</h3>
<p>Get information on an event callback from it’s handle.</p>
<p>Get information on an event callback from its handle.</p>
<h4><a class="title-link" name="synopsis" href="#synopsis"></a> Synopsis</h4>
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="n">service</span><span class="p">,</span> <span class="n">kwargs</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">info_listen_event</span><span class="p">(</span><span class="n">handle</span><span class="p">)</span>
</code></pre>
@ -1082,7 +1082,7 @@
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="bp">self</span><span class="o">.</span><span class="n">listen_event</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">mode_event</span><span class="p">,</span> <span class="s">"MODE_CHANGE"</span><span class="p">)</span>
</code></pre>
</div>
<p>Home Assistant can send these events in a variety of other places - within automations, and also directly from Alexa intents. Home Assistant can also listen for custom events with it’s automation component. This can be used to signal from AppDaemon code back to Home Assistant. Here is a sample automation:</p>
<p>Home Assistant can send these events in a variety of other places - within automations, and also directly from Alexa intents. Home Assistant can also listen for custom events with its automation component. This can be used to signal from AppDaemon code back to Home Assistant. Here is a sample automation:</p>
<div class="language-yaml highlighter-rouge"><pre class="highlight"><code><span class="s">automation</span><span class="pi">:</span>
<span class="s">trigger</span><span class="pi">:</span>
<span class="s">platform</span><span class="pi">:</span> <span class="s">event</span>
@ -1401,7 +1401,7 @@
<h2><a class="title-link" name="time-travel" href="#time-travel"></a> Time Travel</h2>
<p>OK, time travel sadly isn’t really possible but it can be very useful when testing Apps. For instance, imagine you have an App that turns a light on every day at sunset. It might be nice to test it without waiting for Sunset - and with AppDaemon’s “Time Travel” features you can.</p>
<h3><a class="title-link" name="choosing-a-start-time" href="#choosing-a-start-time"></a> Choosing a Start Time</h3>
<p>Internally, AppDaemon keeps track of it’s own time relative to when it was started. This make is possible to start AppDaemon with a different start time and date to the current time. For instance to test that sunset App, start AppDaemon at a time just before sunset and see if it works as expected. To do this, simply use the “-s” argument on AppDaemon’s command line. e,g,:</p>
<p>Internally, AppDaemon keeps track of its own time relative to when it was started. This make is possible to start AppDaemon with a different start time and date to the current time. For instance to test that sunset App, start AppDaemon at a time just before sunset and see if it works as expected. To do this, simply use the “-s” argument on AppDaemon’s command line. e,g,:</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>appdaemon -s <span class="s2">"2016-06-06 19:16:00"</span>
2016-09-06 17:16:00 INFO AppDaemon Version 1.3.2 starting
2016-09-06 17:16:00 INFO Got initial state