2464 lines
No EOL
177 KiB
HTML
2464 lines
No EOL
177 KiB
HTML
<!doctype html>
|
||
<!--[if lt IE 7]> <html class="no-js lt-ie9 lt-ie8 lt-ie7"> <![endif]-->
|
||
<!--[if IE 7]> <html class="no-js lt-ie9 lt-ie8"> <![endif]-->
|
||
<!--[if IE 8]> <html class="no-js lt-ie9"> <![endif]-->
|
||
<!--[if gt IE 8]><!--> <html> <!--<![endif]-->
|
||
|
||
<head>
|
||
<meta charset="utf-8">
|
||
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
|
||
<title>AppDaemon API Reference - Home Assistant</title>
|
||
<meta name="author" content="Home Assistant">
|
||
<meta name="description" content="AppDaemon API Reference">
|
||
|
||
<meta name="viewport" content="width=device-width">
|
||
<link rel="canonical" href="https://home-assistant.io/docs/ecosystem/appdaemon/api/">
|
||
|
||
<meta property="fb:app_id" content="338291289691179">
|
||
<meta property="og:title" content="AppDaemon API Reference">
|
||
<meta property="og:site_name" content="Home Assistant">
|
||
<meta property="og:url" content="https://home-assistant.io/docs/ecosystem/appdaemon/api/">
|
||
<meta property="og:type" content="article">
|
||
<meta property="og:description" content="AppDaemon API Reference">
|
||
<meta property="og:image" content="https://home-assistant.io/images/default-social.png">
|
||
|
||
<meta name="twitter:card" content="summary_large_image">
|
||
<meta name="twitter:site" content="@home_assistant">
|
||
|
||
<meta name="twitter:title" content="AppDaemon API Reference">
|
||
<meta name="twitter:description" content="AppDaemon API Reference">
|
||
<meta name="twitter:image" content="https://home-assistant.io/images/default-social.png">
|
||
|
||
<link href="/stylesheets/screen.css" media="screen, projection" rel="stylesheet">
|
||
<link href="/atom.xml" rel="alternate" title="Home Assistant" type="application/atom+xml">
|
||
<link rel='shortcut icon' href='/images/favicon.ico' />
|
||
<link rel='icon' type='image/png' href='/images/favicon-192x192.png' sizes='192x192' />
|
||
</head>
|
||
|
||
<body >
|
||
|
||
<header>
|
||
<div class="grid-wrapper">
|
||
<div class="grid">
|
||
|
||
<div class="grid__item three-tenths lap-two-sixths palm-one-whole ha-title">
|
||
<a href="/" class="site-title">
|
||
<img width='40' src='/demo/favicon-192x192.png'>
|
||
<span>Home Assistant</span>
|
||
</a>
|
||
</div>
|
||
|
||
<div class="grid__item seven-tenths lap-four-sixths palm-one-whole">
|
||
<nav>
|
||
<input type="checkbox" id="toggle">
|
||
<label for="toggle" class="toggle" data-open="Main Menu" data-close="Close Menu"></label>
|
||
<ul class="menu pull-right">
|
||
|
||
<li><a href="/getting-started/">Getting started</a></li>
|
||
<li><a href="/components/">Components</a></li>
|
||
<li><a href="/docs/">Docs</a></li>
|
||
<li><a href="/cookbook/">Examples</a></li>
|
||
<li><a href="/developers/">Developers</a></li>
|
||
<li><a href="/blog/">Blog</a></li>
|
||
<li><a href="/help/">Need help?</a></li>
|
||
</ul>
|
||
</nav>
|
||
</div>
|
||
|
||
</div>
|
||
</div>
|
||
</header>
|
||
|
||
|
||
|
||
<div class="grid-wrapper">
|
||
<div class="grid grid-center">
|
||
|
||
<div class="grid__item two-thirds lap-one-whole palm-one-whole">
|
||
|
||
|
||
<article class="page">
|
||
|
||
|
||
<div class='edit-github'><a href='https://github.com/home-assistant/home-assistant.github.io/tree/current/source/_docs/ecosystem/appdaemon/api.markdown'>Edit this page on GitHub</a></div>
|
||
|
||
|
||
|
||
<header>
|
||
<h1 class="title indent">
|
||
AppDaemon API Reference
|
||
</h1>
|
||
</header>
|
||
<hr class="divider">
|
||
|
||
|
||
<h2><a class="title-link" name="anatomy-of-an-app" href="#anatomy-of-an-app"></a> Anatomy of an App</h2>
|
||
|
||
<p>Automations in AppDaemon are performed by creating a piece of code (essentially a Python Class) and then instantiating it as an Object one or more times by configuring it as an App in the configuration file. The App is given a chance to register itself for whatever events it wants to subscribe to, and AppDaemon will then make calls back into the Object’s code when those events occur, allowing the App to respond to the event with some kind of action.</p>
|
||
|
||
<p>The first step is to create a unique file within the apps directory (as defined in the <code class="highlighter-rouge">[AppDaemon]</code> section of configuration file). This file is in fact a Python module, and is expected to contain one or more classes derived from the supplied <code class="highlighter-rouge">AppDaemon</code> class, imported from the supplied <code class="highlighter-rouge">homeassistant.appapi</code> module. The start of an app might look like this:</p>
|
||
|
||
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="kn">import</span> <span class="nn">homeassistant.appapi</span> <span class="kn">as</span> <span class="nn">appapi</span>
|
||
|
||
<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>
|
||
|
||
<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>There are several circumstances under which <code class="highlighter-rouge">initialize()</code> might be called:</p>
|
||
|
||
<ul>
|
||
<li>Initial start of AppDaemon</li>
|
||
<li>Following a change to the Class code</li>
|
||
<li>Following a change to the module parameters</li>
|
||
<li>Following initial configuration of an app</li>
|
||
<li>Following a change in the status of Daylight Savings Time</li>
|
||
<li>Following a restart of Home Assistant</li>
|
||
</ul>
|
||
|
||
<p>In every case, the App is responsible for recreating any state it might need as if it were the first time it was ever started. If <code class="highlighter-rouge">initialize()</code> is called, the app can safely assume that it is either being loaded for the first time, or that all callbacks and timers have been cancelled. In either case, the APP will need to recreate them. Depending upon the application it may be desirable for the App to establish state such as whether or not a particular light is on, within the <code class="highlighter-rouge">initialize()</code> function to ensure that everything is as expected or to make immediate remedial action (e.g. turn off a light that might have been left on by mistake when the app was restarted).</p>
|
||
|
||
<p>After the <code class="highlighter-rouge">initialize()</code> function is in place, the rest of the app consists of functions that are called by the various callback mechanisms, and any additional functions the user wants to add as part of the program logic. Apps are able to subscribe to 2 main classes of events:</p>
|
||
|
||
<ul>
|
||
<li>Scheduled Events</li>
|
||
<li>State Change Events</li>
|
||
</ul>
|
||
|
||
<p>These, along with their various subscription calls and helper functions, will be described in detail in later sections.</p>
|
||
|
||
<p>To wrap up this section, here is a complete functioning App (with comments):</p>
|
||
|
||
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="kn">import</span> <span class="nn">homeassistant.appapi</span> <span class="kn">as</span> <span class="nn">appapi</span>
|
||
<span class="kn">import</span> <span class="nn">datetime</span>
|
||
|
||
<span class="c"># Declare Class</span>
|
||
<span class="k">class</span> <span class="nc">NightLight</span><span class="p">(</span><span class="n">appapi</span><span class="o">.</span><span class="n">AppDaemon</span><span class="p">):</span>
|
||
<span class="c">#initialize() function which will be called at startup and reload</span>
|
||
<span class="k">def</span> <span class="nf">initialize</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
|
||
<span class="c"># Create a time object for 7pm</span>
|
||
<span class="n">time</span> <span class="o">=</span> <span class="n">datetime</span><span class="o">.</span><span class="n">time</span><span class="p">(</span><span class="mi">19</span><span class="p">,</span> <span class="mo">00</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span>
|
||
<span class="c"># Schedule a daily callback that will call run_daily() at 7pm every night</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">run_daily</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">run_daily_callback</span><span class="p">,</span> <span class="n">time</span><span class="p">)</span>
|
||
|
||
<span class="c"># Our callback function will be called by the scheduler every day at 7pm</span>
|
||
<span class="k">def</span> <span class="nf">run_daily_callback</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">kwargs</span><span class="p">):</span>
|
||
<span class="c"># Call to Home Assistant to turn the porch light on</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">turn_on</span><span class="p">(</span><span class="s">"light.porch"</span><span class="p">)</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<p>To summarize - an App’s lifecycle consists of being initialized, which allows it to set one or more state and/or schedule callbacks. When those callbacks are activated, the App will typically use one of the Service Calling calls to effect some change to the devices of the system and then wait for the next relevant state change. That’s all there is to it!</p>
|
||
|
||
<h2><a class="title-link" name="about-the-api" href="#about-the-api"></a> About the API</h2>
|
||
|
||
<p>The implementation of the API is located in the AppDaemon class that Apps are derived from. The code for the functions is therefore available to the App simply by invoking the name of the function from the object namespace using the <code class="highlighter-rouge">self</code> keyword, as in the above examples. <code class="highlighter-rouge">self.turn_on()</code> for example is just a method defined in the parent class and made available to the child. This design decision was made to simplify some of the implementation and hide passing of unnecessary variables during the API invocation.</p>
|
||
|
||
<h2><a class="title-link" name="configuration-of-apps" href="#configuration-of-apps"></a> Configuration of Apps</h2>
|
||
<p>Apps are configured by specifying new sections in the configuration file. <code class="highlighter-rouge">[AppDaemon]</code> is a reserved section, for configuration of AppDaemon itself. The name of the section is the name the App is referred to within the system in log files etc. and must be unique.</p>
|
||
|
||
<p>To configure a new App you need a minimum of two directives:</p>
|
||
|
||
<ul>
|
||
<li><code class="highlighter-rouge">module</code> - the name of the module (without the <code class="highlighter-rouge">.py</code>) that contains the class to be used for this App</li>
|
||
<li><code class="highlighter-rouge">class</code> - the name of the class as defined within the module for the APPs code</li>
|
||
</ul>
|
||
|
||
<p>Although the section/App name must be unique, it is possible to re-use a class as many times as you want, and conversely to put as many classes in a module as you want. A sample definition for a new App might look as follows:</p>
|
||
|
||
<div class="language-ini highlighter-rouge"><pre class="highlight"><code><span class="nn">[newapp]</span>
|
||
<span class="py">module</span> <span class="p">=</span> <span class="s">new</span>
|
||
<span class="py">class</span> <span class="p">=</span> <span class="s">NewApp</span>
|
||
</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>
|
||
|
||
<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>
|
||
<li>Add the App to the configuration file</li>
|
||
<li>There is no number 3</li>
|
||
</ol>
|
||
|
||
<h2><a class="title-link" name="reloading-modules-and-classes" href="#reloading-modules-and-classes"></a> Reloading Modules and Classes</h2>
|
||
|
||
<p>Reloading of modules is automatic. When the system spots a change in a module, it will automatically reload and recompile the module. It will also figure out which Apps were using that Module and restart them, causing all of their existing callbacks to be cleared, and their <code class="highlighter-rouge">initialize()</code> function to be called.</p>
|
||
|
||
<p>The same is true if changes are made to an App’s configuration - changing the class, or arguments (see later) will cause that app to be reloaded in the same way. The system is also capable of detecting if a new app has been added, or if one has been removed, and it will act appropriately, starting the new app immediately and removing all callbacks for the removed app.</p>
|
||
|
||
<p>The suggested order for creating a new App is to add the module code first and work until it compiles cleanly, and only then add an entry in the configuration file to actually run it. A good workflow is to continuously monitor the error file (using <code class="highlighter-rouge">tail -f</code> on Linux for instance) to ensure that errors are seen and can be remedied.</p>
|
||
|
||
<h2><a class="title-link" name="passing-arguments-to-apps" href="#passing-arguments-to-apps"></a> Passing Arguments to Apps</h2>
|
||
|
||
<p>There wouldn’t be much point in being able to run multiple versions of an App if there wasn’t some way to instruct them to do something different. For this reason it is possible to pass any required arguments to an App, which are then made available to the object at runtime. The arguments themselves can be called anything (apart from <code class="highlighter-rouge">module</code> or <code class="highlighter-rouge">class</code>) and are simply added into the section after the 2 mandatory directives like so:</p>
|
||
|
||
<div class="language-ini highlighter-rouge"><pre class="highlight"><code><span class="nn">[MyApp]</span>
|
||
<span class="py">module</span> <span class="p">=</span> <span class="s">myapp</span>
|
||
<span class="py">class</span> <span class="p">=</span> <span class="s">MyApp</span>
|
||
<span class="py">param1</span> <span class="p">=</span> <span class="s">spam</span>
|
||
<span class="py">param2</span> <span class="p">=</span> <span class="s">eggs</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<p>Within the Apps code, the 2 parameters (as well as the module and class) are available as a dictionary called <code class="highlighter-rouge">args</code>, and accessed as follows:</p>
|
||
|
||
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="n">param1</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">args</span><span class="p">[</span><span class="s">"param1"</span><span class="p">]</span>
|
||
<span class="n">param2</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">args</span><span class="p">[</span><span class="s">"param2"</span><span class="p">]</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<p>A use case for this might be an App that detects motion and turns on a light. If you have 3 places you want to run this, rather than hardcoding this into 3 separate Apps, you need only code a single app and instantiate it 3 times with different arguments. It might look something like this:</p>
|
||
|
||
<div class="language-ini highlighter-rouge"><pre class="highlight"><code><span class="nn">[downstairs_motion_light]</span>
|
||
<span class="py">module</span> <span class="p">=</span> <span class="s">motion_light</span>
|
||
<span class="py">class</span> <span class="p">=</span> <span class="s">MotionLight</span>
|
||
<span class="py">sensor</span> <span class="p">=</span> <span class="s">binary_sensor.downstairs_hall</span>
|
||
<span class="py">light</span> <span class="p">=</span> <span class="s">light.downstairs_hall</span>
|
||
<span class="nn">[upstairs_motion_light]</span>
|
||
<span class="py">module</span> <span class="p">=</span> <span class="s">motion_light</span>
|
||
<span class="py">class</span> <span class="p">=</span> <span class="s">MotionLight</span>
|
||
<span class="py">sensor</span> <span class="p">=</span> <span class="s">binary_sensor.upstairs_hall</span>
|
||
<span class="py">light</span> <span class="p">=</span> <span class="s">light.upstairs_hall</span>
|
||
<span class="nn">[garage_motion_light]</span>
|
||
<span class="py">module</span> <span class="p">=</span> <span class="s">motion_light</span>
|
||
<span class="py">class</span> <span class="p">=</span> <span class="s">MotionLight</span>
|
||
<span class="py">sensor</span> <span class="p">=</span> <span class="s">binary_sensor.garage</span>
|
||
<span class="py">light</span> <span class="p">=</span> <span class="s">light.garage</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<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>
|
||
|
||
<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>
|
||
<span class="py">constrain_presence</span> <span class="p">=</span> <span class="s">noone</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<p>Now, although the <code class="highlighter-rouge">initialize()</code> function will be called for MyClass, and it will have a chance to register as many callbacks as it desires, none of the callbacks will execute, in this case, until everyone has left. This could be useful for an interior motion detector App for instance. There are several different types of constraints:</p>
|
||
|
||
<ul>
|
||
<li>input_boolean</li>
|
||
<li>input_select</li>
|
||
<li>presence</li>
|
||
<li>time</li>
|
||
</ul>
|
||
|
||
<p>An App can have as many or as few as are required. When more than one constraint is present, they must all evaluate to true to allow the callbacks to be called. Constraints becoming true are not an event in their own right, but if they are all true at a point in time, the next callback that would otherwise been blocked due to constraint failure will now be called. Similarly, if one of the constraints becomes false, the next callback that would otherwise have been called will be blocked.</p>
|
||
|
||
<p>They are described individually below.</p>
|
||
|
||
<h3><a class="title-link" name="input_boolean" href="#input_boolean"></a> input_boolean</h3>
|
||
<p>By default, the input_boolean constraint prevents callbacks unless the specified input_boolean is set to “on”. This is useful to allow certain Apps to be turned on and off from the user interface. For example:</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>
|
||
<span class="py">constrain_input_boolean</span> <span class="p">=</span> <span class="s">input_boolean.enable_motion_detection</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<p>If you want to reverse the logic so the constraint is only called when the input_boolean is off, use the optional state parameter by appending “,off” to the argument, e.g.:</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>
|
||
<span class="py">constrain_input_boolean</span> <span class="p">=</span> <span class="s">input_boolean.enable_motion_detection,off</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h3><a class="title-link" name="input_select" href="#input_select"></a> input_select</h3>
|
||
<p>The input_select constraint prevents callbacks unless the specified input_select is set to one or more of the nominated (comma separated) values. This is useful to allow certain Apps to be turned on and off according to some flag, e.g. a house mode flag.</p>
|
||
|
||
<div class="language-ini highlighter-rouge"><pre class="highlight"><code><span class="c"># Single value
|
||
</span><span class="py">constrain_input_select</span> <span class="p">=</span> <span class="s">input_select.house_mode,Day</span>
|
||
<span class="c"># or multiple values
|
||
</span><span class="py">constrain_input_select</span> <span class="p">=</span> <span class="s">input_select.house_mode,Day,Evening,Night</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h3><a class="title-link" name="presence" href="#presence"></a> presence</h3>
|
||
<p>The presence constraint will constrain based on presence of device trackers. It takes 3 possible values:</p>
|
||
<ul>
|
||
<li><code class="highlighter-rouge">noone</code> - only allow callback execution when no one is home</li>
|
||
<li><code class="highlighter-rouge">anyone</code> - only allow callback execution when one or more person is home</li>
|
||
<li><code class="highlighter-rouge">everyone</code> - only allow callback execution when everyone is home</li>
|
||
</ul>
|
||
|
||
<div class="language-ini highlighter-rouge"><pre class="highlight"><code><span class="py">constrain_presence</span> <span class="p">=</span> <span class="s">anyone</span>
|
||
<span class="c"># or
|
||
</span><span class="py">constrain_presence</span> <span class="p">=</span> <span class="s">someone</span>
|
||
<span class="c"># or
|
||
</span><span class="py">constrain_presence</span> <span class="p">=</span> <span class="s">noone</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h3><a class="title-link" name="time" href="#time"></a> time</h3>
|
||
<p>The time constraint consists of 2 variables, <code class="highlighter-rouge">constrain_start_time</code> and <code class="highlighter-rouge">constrain_end_time</code>. Callbacks will only be executed if the current time is between the start and end times.</p>
|
||
<ul>
|
||
<li>If both are absent no time constraint will exist</li>
|
||
<li>If only start is present, end will default to 1 second before midnight</li>
|
||
<li>If only end is present, start will default to midnight</li>
|
||
</ul>
|
||
|
||
<p>The times are specified in a string format with one of the following formats:</p>
|
||
<ul>
|
||
<li>HH:MM:SS - the time in Hours Minutes and Seconds, 24 hour format.</li>
|
||
<li>
|
||
<table>
|
||
<tbody>
|
||
<tr>
|
||
<td><code class="highlighter-rouge">sunrise</code></td>
|
||
<td><code class="highlighter-rouge">sunset</code> [+</td>
|
||
<td>- HH:MM:SS]- time of the next sunrise or sunset with an optional positive or negative offset in Hours Minutes and seconds</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</li>
|
||
</ul>
|
||
|
||
<p>The time based constraint system correctly interprets start and end times that span midnight.</p>
|
||
|
||
<div class="language-ini highlighter-rouge"><pre class="highlight"><code><span class="c"># Run between 8am and 10pm
|
||
</span><span class="py">constrain_start_time</span> <span class="p">=</span> <span class="s">08:00:00</span>
|
||
<span class="py">constrain_end_time</span> <span class="p">=</span> <span class="s">22:00:00</span>
|
||
<span class="c"># Run between sunrise and sunset
|
||
</span><span class="py">constrain_start_time</span> <span class="p">=</span> <span class="s">sunrise</span>
|
||
<span class="py">constrain_end_time</span> <span class="p">=</span> <span class="s">sunset</span>
|
||
<span class="c"># Run between 45 minutes before sunset and 45 minutes after sunrise the next day
|
||
</span><span class="py">constrain_start_time</span> <span class="p">=</span> <span class="s">sunset - 00:45:00</span>
|
||
<span class="py">constrain_end_time</span> <span class="p">=</span> <span class="s">sunrise + 00:45:00</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h3><a class="title-link" name="days" href="#days"></a> days</h3>
|
||
<p>The day constraint consists of as list of days for which the callbacks will fire, e.g.</p>
|
||
|
||
<div class="language-ini highlighter-rouge"><pre class="highlight"><code><span class="py">constrain_days</span> <span class="p">=</span> <span class="s">mon,tue,wed</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<p>Callback constraints can also be applied to individual callbacks within Apps, see later for more details.</p>
|
||
|
||
<h2><a class="title-link" name="a-note-on-threading" href="#a-note-on-threading"></a> A Note on Threading</h2>
|
||
|
||
<p>AppDaemon is multithreaded. This means that any time code within an App is executed, it is executed by one of many threads. This is generally not a particularly important consideration for this application; in general, the execution time of callbacks is expected to be far quicker than the frequency of events causing them. However, it should be noted for completeness, that it is certainly possible for different pieces of code within the App to be executed concurrently, so some care may be necessary if different callback for instance inspect and change shared variables. This is a fairly standard caveat with concurrent programming, and if you know enough to want to do this, then you should know enough to put appropriate safeguards in place. For the average user however this shouldn’t be an issue. If there are sufficient use cases to warrant it, I will consider adding locking to the function invocations to make the entire infrastructure threadsafe, but I am not convinced that it is necessary.</p>
|
||
|
||
<p>An additional caveat of a threaded worker pool environment is that it is the expectation that none of the callbacks tie threads up for a significant amount of time. To do so would eventually lead to thread exhaustion, which would make the system run behind events. No events would be lost as they would be queued, but callbacks would be delayed which is a bad thing.</p>
|
||
|
||
<p>Given the above, NEVER use Python’s <code class="highlighter-rouge">time.sleep()</code> if you want to perform an operation some time in the future, as this will tie up a thread for the period of the sleep. Instead use the scheduler’s <code class="highlighter-rouge">run_in()</code> function which will allow you to delay without blocking any threads.</p>
|
||
|
||
<h2><a class="title-link" name="state-operations" href="#state-operations"></a> State Operations</h2>
|
||
|
||
<h3><a class="title-link" name="a-note-on-home-assistant-state" href="#a-note-on-home-assistant-state"></a> A note on Home Assistant State</h3>
|
||
|
||
<p>State within Home Assistant is stored as a collection of dictionaries, one for each entity. Each entity’s dictionary will have some common fields and a number of entity type specific fields The state for an entity will always have the attributes:</p>
|
||
|
||
<ul>
|
||
<li><code class="highlighter-rouge">last_updated</code></li>
|
||
<li><code class="highlighter-rouge">last_changed</code></li>
|
||
<li><code class="highlighter-rouge">state</code></li>
|
||
</ul>
|
||
|
||
<p>Any other attributes such as brightness for a lamp will only be present if the entity supports them, and will be stored in a sub-dictionary called <code class="highlighter-rouge">attributes</code>. When specifying these optional attributes in the <code class="highlighter-rouge">get_state()</code> call, no special distinction is required between the main attributes and the optional ones - <code class="highlighter-rouge">get_state()</code> will figure it out for you.</p>
|
||
|
||
<p>Also bear in mind that some attributes such as brightness for a light, will not be present when the light is off.</p>
|
||
|
||
<p>In most cases, the attribute <code class="highlighter-rouge">state</code> has the most important value in it, e.g. for a light or switch this will be <code class="highlighter-rouge">on</code> or <code class="highlighter-rouge">off</code>, for a sensor it will be the value of that sensor. Many of the AppDaemon API calls and callbacks will implicitly return the value of state unless told to do otherwise.</p>
|
||
|
||
<h3><a class="title-link" name="get_state" href="#get_state"></a> get_state()</h3>
|
||
|
||
<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">get_state</span><span class="p">(</span><span class="n">entity</span> <span class="o">=</span> <span class="bp">None</span><span class="p">,</span> <span class="n">attribute</span> <span class="o">=</span> <span class="bp">None</span><span class="p">)</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<p><code class="highlighter-rouge">get_state()</code> is used to query the state of any component within Home Assistant. State updates are continuously tracked so this call runs locally and does not require AppDaemon to call back to Home Assistant and as such is very efficient.</p>
|
||
|
||
<h4><a class="title-link" name="returns" href="#returns"></a> Returns</h4>
|
||
|
||
<p><code class="highlighter-rouge">get_state()</code> returns a <code class="highlighter-rouge">dictionary</code> or single value, the structure of which varies according to the parameters used.</p>
|
||
|
||
<h4><a class="title-link" name="parameters" href="#parameters"></a> Parameters</h4>
|
||
|
||
<p>All parameters are optional, and if <code class="highlighter-rouge">get_state()</code> is called with no parameters it will return the entire state of Home Assistant at that given time. This will consist of a dictionary with a key for each entity. Under that key will be the standard entity state information.</p>
|
||
|
||
<h5><a class="title-link" name="entity" href="#entity"></a> entity</h5>
|
||
|
||
<p>This is the name of an entity or device type. If just a device type is provided, e.g. <code class="highlighter-rouge">light</code> or <code class="highlighter-rouge">binary_sensor</code>, <code class="highlighter-rouge">get_state()</code> will return a dictionary of all devices of that type, indexed by the entity_id, containing all the state for each entity.</p>
|
||
|
||
<p>If a fully qualified <code class="highlighter-rouge">entity_id</code> is provided, <code class="highlighter-rouge">get_state()</code> will return the state attribute for that entity, e.g. <code class="highlighter-rouge">on</code> or <code class="highlighter-rouge">off</code> for a light.</p>
|
||
|
||
<h5><a class="title-link" name="attribute" href="#attribute"></a> attribute</h5>
|
||
|
||
<p>Name of an attribute within the entity state object. If this parameter is specified in addition to a fully qualified <code class="highlighter-rouge">entity_id</code>, a single value representing the attribute will be returned, or <code class="highlighter-rouge">None</code> if it is not present.</p>
|
||
|
||
<p>The value <code class="highlighter-rouge">all</code> for attribute has special significance and will return the entire state dictionary for the specified entity rather than an individual attribute value.</p>
|
||
|
||
<h4><a class="title-link" name="examples" href="#examples"></a> Examples</h4>
|
||
|
||
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="c"># Return state for the entire system</span>
|
||
<span class="n">state</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">get_state</span><span class="p">()</span>
|
||
|
||
<span class="c"># Return state for all switches in the system</span>
|
||
<span class="n">state</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">get_state</span><span class="p">(</span><span class="s">"switch"</span><span class="p">)</span>
|
||
|
||
<span class="c"># Return the state attribute for light.office_1</span>
|
||
<span class="n">state</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">get_state</span><span class="p">(</span><span class="s">"light.office_1"</span><span class="p">)</span>
|
||
|
||
<span class="c"># Return the brightness attribute for light.office_1</span>
|
||
<span class="n">state</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">get_state</span><span class="p">(</span><span class="s">"light.office_1"</span><span class="p">,</span> <span class="s">"brightness"</span><span class="p">)</span>
|
||
|
||
<span class="c"># Return the entire state for light.office_1</span>
|
||
<span class="n">state</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">get_state</span><span class="p">(</span><span class="s">"light.office_1"</span><span class="p">,</span> <span class="s">"all"</span><span class="p">)</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h3><a class="title-link" name="set_state" href="#set_state"></a> set_state()</h3>
|
||
|
||
<p><code class="highlighter-rouge">set_state()</code> will make a call back to Home Assistant and make changes to the internal state of Home Assistant. This is not something that you would usually want to do and the applications are limited however the call is included for completeness. Note that for instance, setting the state of a light to <code class="highlighter-rouge">on</code> won’t actually switch the device on, it will merely change the state of the device in Home Assistant so that it no longer reflects reality. In most cases, the state will be corrected the next time Home Assistant polls the device or someone causes a state change manually. To effect actual changes of devices use one of the service call functions.</p>
|
||
|
||
<p>One possible use case for <code class="highlighter-rouge">set_state()</code> is for testing. If for instance you are writing an App to turn on a light when it gets dark according to a luminance sensor, you can use <code class="highlighter-rouge">set_state()</code> to temporarily change the light level reported by the sensor to test your program. However this is also possible using the developer tools.</p>
|
||
|
||
<p>At the time of writing, it appears that no checking is done as to whether or not the entity exists, so it is possible to add entirely new entries to Home Assistant’s state with this call.</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">set_state</span><span class="p">(</span><span class="n">entity_id</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h4><a class="title-link" name="returns" href="#returns"></a> Returns</h4>
|
||
|
||
<p><code class="highlighter-rouge">set_state()</code> returns a dictionary representing the state of the device after the call has completed.</p>
|
||
|
||
<h4><a class="title-link" name="parameters" href="#parameters"></a> Parameters</h4>
|
||
|
||
<h5><a class="title-link" name="entity_id" href="#entity_id"></a> entity_id</h5>
|
||
|
||
<p>Entity id for which the state is to be set, e.g. <code class="highlighter-rouge">light.office_1</code>.</p>
|
||
|
||
<h5><a class="title-link" name="values" href="#values"></a> values</h5>
|
||
|
||
<p>A list of keyword values to be changed or added to the entities state. e.g. <code class="highlighter-rouge">state = "off"</code>. Note that any optional attributes such as colors for bulbs etc, need to reside in a dictionary called <code class="highlighter-rouge">attributes</code>; see the example.</p>
|
||
|
||
<h4><a class="title-link" name="examples" href="#examples"></a> Examples</h4>
|
||
|
||
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="n">status</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">set_state</span><span class="p">(</span><span class="s">"light.office_1"</span><span class="p">,</span> <span class="n">state</span> <span class="o">=</span> <span class="s">"on"</span><span class="p">,</span> <span class="n">attributes</span> <span class="o">=</span> <span class="p">{</span><span class="s">"color_name"</span><span class="p">:</span> <span class="s">"red"</span><span class="p">})</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h3><a class="title-link" name="about-callbacks" href="#about-callbacks"></a> About Callbacks</h3>
|
||
|
||
<p>A large proportion of home automation revolves around waiting for something to happen and then reacting to it; a light level drops, the sun rises, a door opens etc. Home Assistant keeps track of every state change that occurs within the system and streams that information to AppDaemon almost immediately.</p>
|
||
|
||
<p>An individual App however usually doesn’t care about the majority of state changes going on in the system; Apps usually care about something very specific, like a specific sensor or light. Apps need a way to be notified when a state change happens that they care about, and be able to ignore the rest. They do this through registering callbacks. A callback allows the App to describe exactly what it is interested in, and tells AppDaemon to make a call into its code in a specific place to be able to react to it - this is a very familiar concept to anyone familiar with event-based programming.</p>
|
||
|
||
<p>There are 3 types of callbacks within AppDaemon:</p>
|
||
|
||
<ul>
|
||
<li>State Callbacks - react to a change in state</li>
|
||
<li>Scheduler Callbacks - react to a specific time or interval</li>
|
||
<li>Event Callbacks - react to specific Home Assistant and Appdaemon events.</li>
|
||
</ul>
|
||
|
||
<p>All callbacks allow the user to specify additional parameters to be handed to the callback via the standard Python <code class="highlighter-rouge">**kwargs</code> mechanism for greater flexibility.</p>
|
||
|
||
<h3><a class="title-link" name="about-registering-callbacks" href="#about-registering-callbacks"></a> About Registering Callbacks</h3>
|
||
|
||
<p>Each of the various types of callback have their own function or functions for registering the callback:</p>
|
||
|
||
<ul>
|
||
<li><code class="highlighter-rouge">listen_state()</code> for state callbacks</li>
|
||
<li>Various scheduler calls such as <code class="highlighter-rouge">run_once()</code> for scheduler callbacks</li>
|
||
<li><code class="highlighter-rouge">listen_event()</code> for event callbacks.</li>
|
||
</ul>
|
||
|
||
<p>Each type of callback shares a number of common mechanisms that increase flexibility.</p>
|
||
|
||
<h4><a class="title-link" name="callback-level-constraints" href="#callback-level-constraints"></a> Callback Level Constraints</h4>
|
||
|
||
<p>When registering a callback, you can add constraints identical to the Application level constraints described earlier. The difference is that a constraint applied to an individual callback only affects that callback and no other. The constraints are applied by adding Python keyword-value style arguments after the positional arguments. The parameters themselves are named identically to the previously described constraints and have identical functionality. For instance, adding:</p>
|
||
|
||
<p><code class="highlighter-rouge">constrain_presence="everyone"</code></p>
|
||
|
||
<p>to a callback registration will ensure that the callback is only run if the callback conditions are met and in addition everyone is present although any other callbacks might run whenever their event fires if they have no constraints.</p>
|
||
|
||
<p>For example:</p>
|
||
|
||
<p><code class="highlighter-rouge">self.listen_state(self.motion, "binary_sensor.drive", constrain_presence="everyone")</code></p>
|
||
|
||
<h4><a class="title-link" name="user-arguments" href="#user-arguments"></a> User Arguments</h4>
|
||
|
||
<p>Any callback has the ability to allow the App creator to pass through arbitrary keyword arguments that will be presented to the callback when it is run. The arguments are added after the positional parameters just like the constraints. The only restriction is that they cannot be the same as any constraint name for obvious reasons. For example, to pass the parameter <code class="highlighter-rouge">arg1 = "home assistant"</code> through to a callback you would register a callback as follows:</p>
|
||
|
||
<p><code class="highlighter-rouge">self.listen_state(self.motion, "binary_sensor.drive", arg1="home assistant")</code></p>
|
||
|
||
<p>Then in the callback you could use it as follows:</p>
|
||
|
||
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="k">def</span> <span class="nf">motion</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">entity</span><span class="p">,</span> <span class="n">attribute</span><span class="p">,</span> <span class="n">old</span><span class="p">,</span> <span class="n">new</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="s">"Arg1 is {}"</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">kwargs</span><span class="p">[</span><span class="s">"arg1"</span><span class="p">]))</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h3><a class="title-link" name="state-callbacks" href="#state-callbacks"></a> State Callbacks</h3>
|
||
|
||
<p>AppDaemons’s state callbacks allow an App to listen to a wide variety of events, from every state change in the system, right down to a change of a single attribute of a particular entity. Setting up a callback is done using a single API call <code class="highlighter-rouge">listen_state()</code> which takes various arguments to allow it to do all of the above. Apps can register as many or as few callbacks as they want.</p>
|
||
|
||
<h3><a class="title-link" name="about-state-callback-functions" href="#about-state-callback-functions"></a> About State Callback Functions</h3>
|
||
|
||
<p>When calling back into the App, the App must provide a class function with a known signature for AppDaemon to call. The callback will provide various information to the function to enable the function to respond appropriately. For state callbacks, a class defined callback function should look like this:</p>
|
||
|
||
<div class="language-python highlighter-rouge"><pre class="highlight"><code> <span class="k">def</span> <span class="nf">my_callback</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">entity</span><span class="p">,</span> <span class="n">attribute</span><span class="p">,</span> <span class="n">old</span><span class="p">,</span> <span class="n">new</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
|
||
<span class="o"><</span><span class="n">do</span> <span class="n">some</span> <span class="n">useful</span> <span class="n">work</span> <span class="n">here</span><span class="o">></span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<p>You can call the function whatever you like - you will reference it in the <code class="highlighter-rouge">listen_state()</code> call, and you can create as many callback functions as you need.</p>
|
||
|
||
<p>The parameters have the following meanings:</p>
|
||
|
||
<h4><a class="title-link" name="self" href="#self"></a> self</h4>
|
||
|
||
<p>A standard Python object reference.</p>
|
||
|
||
<h4><a class="title-link" name="entity" href="#entity"></a> entity</h4>
|
||
|
||
<p>Name of the entity the callback was requested for or <code class="highlighter-rouge">None</code>.</p>
|
||
|
||
<h4><a class="title-link" name="attribute" href="#attribute"></a> attribute</h4>
|
||
|
||
<p>Name of the attribute the callback was requested for or <code class="highlighter-rouge">None</code>.</p>
|
||
|
||
<h4><a class="title-link" name="old" href="#old"></a> old</h4>
|
||
|
||
<p>The value of the state before the state change.</p>
|
||
|
||
<h4><a class="title-link" name="new" href="#new"></a> new</h4>
|
||
|
||
<p>The value of the state after the state change.</p>
|
||
|
||
<p><code class="highlighter-rouge">old</code> and <code class="highlighter-rouge">new</code> will have varying types depending on the type of callback.</p>
|
||
|
||
<h4><a class="title-link" name="kwargs" href="#kwargs"></a> **kwargs</h4>
|
||
|
||
<p>A dictionary containing any constraints and/or additional user specific keyword arguments supplied to the <code class="highlighter-rouge">listen_state()</code> call.</p>
|
||
|
||
<h3><a class="title-link" name="listen_state" href="#listen_state"></a> listen_state()</h3>
|
||
|
||
<p><code class="highlighter-rouge">listen_state()</code> allows the user to register a callback for a wide variety of state changes.</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">handle</span> <span class="o">=</span> <span class="n">listen_state</span><span class="p">(</span><span class="n">callback</span><span class="p">,</span> <span class="n">entity</span> <span class="o">=</span> <span class="bp">None</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h4><a class="title-link" name="returns" href="#returns"></a> Returns</h4>
|
||
|
||
<p>A unique identifier that can be used to cancel the callback if required. Since variables created within object methods are local to the function they are created in, and in all likelihood the cancellation will be invoked later in a different function, it is recommended that handles are stored in the object namespace, e.g. <code class="highlighter-rouge">self.handle</code>.</p>
|
||
|
||
<h4><a class="title-link" name="parameters" href="#parameters"></a> Parameters</h4>
|
||
|
||
<p>All parameters except <code class="highlighter-rouge">callback</code> are optional, and if <code class="highlighter-rouge">listen_state()</code> is called with no additional parameters it will subscribe to any state change within Home Assistant.</p>
|
||
|
||
<h5><a class="title-link" name="callback" href="#callback"></a> callback</h5>
|
||
|
||
<p>Function to be invoked when the requested state change occurs. It must conform to the standard State Callback format documented above.</p>
|
||
|
||
<h5><a class="title-link" name="entity" href="#entity"></a> entity</h5>
|
||
|
||
<p>This is the name of an entity or device type. If just a device type is provided, e.g. <code class="highlighter-rouge">light</code> or <code class="highlighter-rouge">binary_sensor</code>, <code class="highlighter-rouge">listen_state()</code> will subscribe to state changes of all devices of that type. If a fully qualified <code class="highlighter-rouge">entity_id</code> is provided, <code class="highlighter-rouge">listen_state()</code> will listen for state changes for just that entity.</p>
|
||
|
||
<p>When called, AppDaemon will supply the callback function, in old and new, with the state attribute for that entity, e.g. <code class="highlighter-rouge">on</code> or <code class="highlighter-rouge">off</code> for a light.</p>
|
||
|
||
<h5><a class="title-link" name="attribute-optional" href="#attribute-optional"></a> attribute (optional)</h5>
|
||
|
||
<p>Name of an attribute within the entity state object. If this parameter is specified in addition to a fully qualified <code class="highlighter-rouge">entity_id</code>, <code class="highlighter-rouge">listen_state()</code> will subscribe to changes for just that attribute within that specific entity. The new and old parameters in the callback function will be provided with a single value representing the attribute.</p>
|
||
|
||
<p>The value <code class="highlighter-rouge">all</code> for attribute has special significance and will listen for any state change within the specified entity, and supply the callback functions with the entire state dictionary for the specified entity rather than an individual attribute value.</p>
|
||
|
||
<h5><a class="title-link" name="new--value-optional" href="#new--value-optional"></a> new = <value> (optional)</value></h5>
|
||
|
||
<p>If <code class="highlighter-rouge">new</code> is supplied as a parameter, callbacks will only be made if the state of the selected attribute (usually <code class="highlighter-rouge">state</code>) in the new state match the value of <code class="highlighter-rouge">new</code>.</p>
|
||
|
||
<h5><a class="title-link" name="old---value-optional" href="#old---value-optional"></a> old = <value> (optional)</value></h5>
|
||
|
||
<p>If <code class="highlighter-rouge">old</code> is supplied as a parameter, callbacks will only be made if the state of the selected attribute (usually <code class="highlighter-rouge">state</code>) in the old state match the value of <code class="highlighter-rouge">old</code>.</p>
|
||
|
||
<p>Note: <code class="highlighter-rouge">old</code> and <code class="highlighter-rouge">new</code> can be used singly or together.</p>
|
||
|
||
<h5><a class="title-link" name="duration---seconds-optional" href="#duration---seconds-optional"></a> duration = <seconds> (optional)</seconds></h5>
|
||
|
||
<p>If duration is supplied as a parameter, the callback will not fire unless the state listened for is maintained for that number of seconds. This makes the most sense if a specific attribute is specified (or the default os <code class="highlighter-rouge">state</code> is used), an in conjunction with the <code class="highlighter-rouge">old</code> or <code class="highlighter-rouge">new</code> parameters, or both. When the callback is called, it is supplied with the values of <code class="highlighter-rouge">entity</code>, <code class="highlighter-rouge">attr</code>, <code class="highlighter-rouge">old</code> and <code class="highlighter-rouge">new</code> that were current at the time the actual event occured, since the assumption is that none of them have changed in the intervening period.</p>
|
||
|
||
<div class="language-python highlighter-rouge"><pre class="highlight"><code> <span class="k">def</span> <span class="nf">my_callback</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="o"><</span><span class="n">do</span> <span class="n">some</span> <span class="n">useful</span> <span class="n">work</span> <span class="n">here</span><span class="o">></span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<p>(Scheduler callbacks are documented in detail laer in this document)</p>
|
||
|
||
<h5><a class="title-link" name="kwargs" href="#kwargs"></a> **kwargs</h5>
|
||
|
||
<p>Zero or more keyword arguments that will be supplied to the callback when it is called.</p>
|
||
|
||
<h4><a class="title-link" name="examples" href="#examples"></a> Examples</h4>
|
||
|
||
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="c"># Listen for any state change and return the state attribute</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">listen_state</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">my_callback</span><span class="p">)</span>
|
||
|
||
<span class="c"># Listen for any state change involving a light and return the state attribute</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">listen_state</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">my_callback</span><span class="p">,</span> <span class="s">"light"</span><span class="p">)</span>
|
||
|
||
<span class="c"># Listen for a state change involving light.office1 and return the state attribute</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">listen_state</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">my_callback</span><span class="p">,</span> <span class="s">"light.office_1"</span><span class="p">)</span>
|
||
|
||
<span class="c"># Listen for a state change involving light.office1 and return the entire state as a dict</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">listen_state</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">my_callback</span><span class="p">,</span> <span class="s">"light.office_1"</span><span class="p">,</span> <span class="n">attribute</span> <span class="o">=</span> <span class="s">"all"</span><span class="p">)</span>
|
||
|
||
<span class="c"># Listen for a state change involving the brightness attribute of light.office1</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">listen_state</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">my_callback</span><span class="p">,</span> <span class="s">"light.office_1"</span><span class="p">,</span> <span class="n">attribute</span> <span class="o">=</span> <span class="s">"brightness"</span><span class="p">)</span>
|
||
|
||
<span class="c"># Listen for a state change involving light.office1 turning on and return the state attribute</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">listen_state</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">my_callback</span><span class="p">,</span> <span class="s">"light.office_1"</span><span class="p">,</span> <span class="n">new</span> <span class="o">=</span> <span class="s">"on"</span><span class="p">)</span>
|
||
|
||
<span class="c"># Listen for a state change involving light.office1 changing from brightness 100 to 200 and return the state attribute</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">listen_state</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">my_callback</span><span class="p">,</span> <span class="s">"light.office_1"</span><span class="p">,</span> <span class="n">old</span> <span class="o">=</span> <span class="s">"100"</span><span class="p">,</span> <span class="n">new</span> <span class="o">=</span> <span class="s">"200"</span><span class="p">)</span>
|
||
|
||
<span class="c"># Listen for a state change involving light.office1 changing to state on and remaining on for a minute</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">listen_state</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">my_callback</span><span class="p">,</span> <span class="s">"light.office_1"</span><span class="p">,</span> <span class="n">new</span> <span class="o">=</span> <span class="s">"on"</span><span class="p">,</span> <span class="n">duration</span> <span class="o">=</span> <span class="mi">60</span><span class="p">)</span>
|
||
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h3><a class="title-link" name="cancel_listen_state" href="#cancel_listen_state"></a> cancel_listen_state()</h3>
|
||
|
||
<p>Cancel a <code class="highlighter-rouge">listen_state()</code> callback. This will mean that the App will no longer be notified for the specific state change that has been cancelled. Other state changes will continue to be monitored.</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">cancel_listen_state</span><span class="p">(</span><span class="n">handle</span><span class="p">)</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h4><a class="title-link" name="returns" href="#returns"></a> Returns</h4>
|
||
|
||
<p>Nothing</p>
|
||
|
||
<h4><a class="title-link" name="parameters" href="#parameters"></a> Parameters</h4>
|
||
|
||
<h5><a class="title-link" name="handle" href="#handle"></a> handle</h5>
|
||
|
||
<p>The handle returned when the <code class="highlighter-rouge">listen_state()</code> call was made.</p>
|
||
|
||
<h4><a class="title-link" name="examples" href="#examples"></a> Examples</h4>
|
||
|
||
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="bp">self</span><span class="o">.</span><span class="n">cancel_listen_state</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">office_light_handle</span><span class="p">)</span>
|
||
</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>
|
||
|
||
<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>
|
||
</div>
|
||
|
||
<h4><a class="title-link" name="returns" href="#returns"></a> Returns</h4>
|
||
|
||
<p>entity, attribute, kwargs - the values supplied when the callback was initially created.</p>
|
||
|
||
<h4><a class="title-link" name="parameters" href="#parameters"></a> Parameters</h4>
|
||
|
||
<h5><a class="title-link" name="handle" href="#handle"></a> handle</h5>
|
||
|
||
<p>The handle returned when the <code class="highlighter-rouge">listen_state()</code> call was made.</p>
|
||
|
||
<h4><a class="title-link" name="examples" href="#examples"></a> Examples</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>
|
||
</div>
|
||
|
||
<h2><a class="title-link" name="scheduler" href="#scheduler"></a> Scheduler</h2>
|
||
|
||
<p>AppDaemon contains a powerful scheduler that is able to run with 1 second resolution to fire off specific events at set times, or after set delays, or even relative to sunrise and sunset. In general, events should be fired less than a second after specified but under certain circumstances there may be short additional delays.</p>
|
||
|
||
<h3><a class="title-link" name="about-schedule-callbacks" href="#about-schedule-callbacks"></a> About Schedule Callbacks</h3>
|
||
|
||
<p>As with State Change callbacks, Scheduler Callbacks expect to call into functions with a known and specific signature and a class defined Scheduler callback function should look like this:</p>
|
||
|
||
<div class="language-python highlighter-rouge"><pre class="highlight"><code> <span class="k">def</span> <span class="nf">my_callback</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="o"><</span><span class="n">do</span> <span class="n">some</span> <span class="n">useful</span> <span class="n">work</span> <span class="n">here</span><span class="o">></span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<p>You can call the function whatever you like; you will reference it in the Scheduler call, and you can create as many callback functions as you need.</p>
|
||
|
||
<p>The parameters have the following meanings:</p>
|
||
|
||
<h4><a class="title-link" name="self" href="#self"></a> self</h4>
|
||
<p>A standard Python object reference</p>
|
||
|
||
<h4><a class="title-link" name="kwargs" href="#kwargs"></a> **kwargs</h4>
|
||
|
||
<p>A dictionary containing Zero or more keyword arguments to be supplied to the callback.</p>
|
||
|
||
<h3><a class="title-link" name="creation-of-scheduler-callbacks" href="#creation-of-scheduler-callbacks"></a> Creation of Scheduler Callbacks</h3>
|
||
|
||
<p>Scheduler callbacks are created through use of a number of convenience functions which can be used to suit the situation.</p>
|
||
|
||
<h4><a class="title-link" name="run_in" href="#run_in"></a> run_in()</h4>
|
||
|
||
<p>Run the callback in a defined number of seconds. This is used to add a delay, for instance a 60 second delay before a light is turned off after it has been triggered by a motion detector. This callback should always be used instead of <code class="highlighter-rouge">time.sleep()</code> as discussed previously.</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="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="n">delay</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h4><a class="title-link" name="returns" href="#returns"></a> Returns</h4>
|
||
|
||
<p>A handle that can be used to cancel the timer.</p>
|
||
|
||
<h4><a class="title-link" name="parameters" href="#parameters"></a> Parameters</h4>
|
||
|
||
<h5>vcallback %}</h5>
|
||
|
||
<p>Function to be invoked when the requested state change occurs. It must conform to the standard Scheduler Callback format documented above.</p>
|
||
|
||
<h5><a class="title-link" name="delay" href="#delay"></a> delay</h5>
|
||
|
||
<p>Delay, in seconds before the callback is invoked.</p>
|
||
|
||
<h5><a class="title-link" name="kwargs" href="#kwargs"></a> **kwargs</h5>
|
||
|
||
<p>Arbitary keyword parameters to be provided to the callback function when it is invoked.</p>
|
||
|
||
<h4><a class="title-link" name="examples" href="#examples"></a> Examples</h4>
|
||
|
||
<div class="language-python highlighter-rouge"><pre class="highlight"><code><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="bp">self</span><span class="o">.</span><span class="n">run_in_c</span><span class="p">)</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="bp">self</span><span class="o">.</span><span class="n">run_in_c</span><span class="p">,</span> <span class="n">title</span> <span class="o">=</span> <span class="s">"run_in5"</span><span class="p">)</span>
|
||
</code></pre>
|
||
</div>
|
||
<h4><a class="title-link" name="run_once" href="#run_once"></a> run_once()</h4>
|
||
|
||
<p>Run the callback once, at the specified time of day. If the time of day is in the past, the callback will occur on the next day.</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="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_once</span><span class="p">(</span><span class="n">callback</span><span class="p">,</span> <span class="n">time</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h4><a class="title-link" name="returns" href="#returns"></a> Returns</h4>
|
||
|
||
<p>A handle that can be used to cancel the timer.</p>
|
||
|
||
<h4><a class="title-link" name="parameters" href="#parameters"></a> Parameters</h4>
|
||
|
||
<h5><a class="title-link" name="callback" href="#callback"></a> callback</h5>
|
||
|
||
<p>Function to be invoked when the requested state change occurs. It must conform to the standard Scheduler Callback format documented above.</p>
|
||
|
||
<h5><a class="title-link" name="time" href="#time"></a> time</h5>
|
||
|
||
<p>A Python <code class="highlighter-rouge">time</code> object that specifies when the callback will occur. If the time specified is in the past, the callback will occur the next day at the specified time.</p>
|
||
|
||
<h5><a class="title-link" name="kwargs" href="#kwargs"></a> **kwargs</h5>
|
||
|
||
<p>Arbitary keyword parameters to be provided to the callback function when it is invoked.</p>
|
||
|
||
<h4><a class="title-link" name="examples" href="#examples"></a> Examples</h4>
|
||
|
||
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="c"># Run at 4pm today, or 4pm tomorrow if it is already after 4pm</span>
|
||
<span class="kn">import</span> <span class="nn">datetime</span>
|
||
<span class="o">...</span>
|
||
<span class="n">runtime</span> <span class="o">=</span> <span class="n">datetime</span><span class="o">.</span><span class="n">time</span><span class="p">(</span><span class="mi">16</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span>
|
||
<span class="n">handle</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">run_once</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">run_once_c</span><span class="p">,</span> <span class="n">runtime</span><span class="p">)</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h4><a class="title-link" name="run_at" href="#run_at"></a> run_at()</h4>
|
||
|
||
<p>Run the callback once, at the specified date and time.</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="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_at</span><span class="p">(</span><span class="n">callback</span><span class="p">,</span> <span class="n">datetime</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h4><a class="title-link" name="returns" href="#returns"></a> Returns</h4>
|
||
|
||
<p>A handle that can be used to cancel the timer. <code class="highlighter-rouge">run_at()</code> will raise an exception if the specified time is in the past.</p>
|
||
|
||
<h4><a class="title-link" name="parameters" href="#parameters"></a> Parameters</h4>
|
||
|
||
<h5><a class="title-link" name="callback" href="#callback"></a> callback</h5>
|
||
|
||
<p>Function to be invoked when the requested state change occurs. It must conform to the standard Scheduler Callback format documented above.</p>
|
||
|
||
<h5><a class="title-link" name="datetime" href="#datetime"></a> datetime</h5>
|
||
|
||
<p>A Python <code class="highlighter-rouge">datetime</code> object that specifies when the callback will occur.</p>
|
||
|
||
<h5><a class="title-link" name="kwargs" href="#kwargs"></a> **kwargs</h5>
|
||
|
||
<p>Arbitary keyword parameters to be provided to the callback function when it is invoked.</p>
|
||
|
||
<h4><a class="title-link" name="examples" href="#examples"></a> Examples</h4>
|
||
|
||
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="c"># Run at 4pm today</span>
|
||
<span class="kn">import</span> <span class="nn">datetime</span>
|
||
<span class="o">...</span>
|
||
<span class="n">runtime</span> <span class="o">=</span> <span class="n">datetime</span><span class="o">.</span><span class="n">time</span><span class="p">(</span><span class="mi">16</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span>
|
||
<span class="n">today</span> <span class="o">=</span> <span class="n">datetime</span><span class="o">.</span><span class="n">date</span><span class="o">.</span><span class="n">today</span><span class="p">()</span>
|
||
<span class="n">event</span> <span class="o">=</span> <span class="n">datetime</span><span class="o">.</span><span class="n">datetime</span><span class="o">.</span><span class="n">combine</span><span class="p">(</span><span class="n">today</span><span class="p">,</span> <span class="n">runtime</span><span class="p">)</span>
|
||
<span class="n">handle</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">run_once</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">run_once_c</span><span class="p">,</span> <span class="n">event</span><span class="p">)</span>
|
||
</code></pre>
|
||
</div>
|
||
<h4><a class="title-link" name="run_daily" href="#run_daily"></a> run_daily()</h4>
|
||
|
||
<p>Execute a callback at the same time every day. If the time has already passed, the function will not be invoked until the following day at the specified time.</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="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_daily</span><span class="p">(</span><span class="n">callback</span><span class="p">,</span> <span class="n">time</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h4><a class="title-link" name="returns" href="#returns"></a> Returns</h4>
|
||
|
||
<p>A handle that can be used to cancel the timer.</p>
|
||
|
||
<h4><a class="title-link" name="parameters" href="#parameters"></a> Parameters</h4>
|
||
|
||
<h5><a class="title-link" name="callback" href="#callback"></a> callback</h5>
|
||
|
||
<p>Function to be invoked when the requested state change occurs. It must conform to the standard Scheduler Callback format documented above.</p>
|
||
|
||
<h5><a class="title-link" name="time" href="#time"></a> time</h5>
|
||
|
||
<p>A Python <code class="highlighter-rouge">time</code> object that specifies when the callback will occur. If the time specified is in the past, the callback will occur the next day at the specified time.</p>
|
||
|
||
<h5><a class="title-link" name="kwargs" href="#kwargs"></a> **kwargs</h5>
|
||
|
||
<p>Arbitary keyword parameters to be provided to the callback function when it is invoked.</p>
|
||
|
||
<h4><a class="title-link" name="examples" href="#examples"></a> Examples</h4>
|
||
|
||
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="c"># Run daily at 7pm</span>
|
||
<span class="kn">import</span> <span class="nn">datetime</span>
|
||
<span class="o">...</span>
|
||
<span class="n">time</span> <span class="o">=</span> <span class="n">datetime</span><span class="o">.</span><span class="n">time</span><span class="p">(</span><span class="mi">19</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">run_daily</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">run_daily_c</span><span class="p">,</span> <span class="n">runtime</span><span class="p">)</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h4><a class="title-link" name="run_hourly" href="#run_hourly"></a> run_hourly()</h4>
|
||
|
||
<p>Execute a callback at the same time every hour. If the time has already passed, the function will not be invoked until the following hour at the specified time.</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="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_hourly</span><span class="p">(</span><span class="n">callback</span><span class="p">,</span> <span class="n">time</span> <span class="o">=</span> <span class="bp">None</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h4><a class="title-link" name="returns" href="#returns"></a> Returns</h4>
|
||
|
||
<p>A handle that can be used to cancel the timer.</p>
|
||
|
||
<h4><a class="title-link" name="parameters" href="#parameters"></a> Parameters</h4>
|
||
|
||
<h5><a class="title-link" name="callback" href="#callback"></a> callback</h5>
|
||
|
||
<p>Function to be invoked when the requested state change occurs. It must conform to the standard Scheduler Callback format documented above.</p>
|
||
|
||
<h5><a class="title-link" name="time" href="#time"></a> time</h5>
|
||
|
||
<p>A Python <code class="highlighter-rouge">time</code> object that specifies when the callback will occur, the hour component of the time object is ignored. If the time specified is in the past, the callback will occur the next hour at the specified time. If time is not supplied, the callback will start an hour from the time that <code class="highlighter-rouge">run_hourly()</code> was executed.</p>
|
||
|
||
<h5><a class="title-link" name="kwargs" href="#kwargs"></a> **kwargs</h5>
|
||
|
||
<p>Arbitary keyword parameters to be provided to the callback function when it is invoked.</p>
|
||
|
||
<h4><a class="title-link" name="examples" href="#examples"></a> Examples</h4>
|
||
|
||
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="c"># Run every hour, on the hour</span>
|
||
<span class="kn">import</span> <span class="nn">datetime</span>
|
||
<span class="o">...</span>
|
||
<span class="n">time</span> <span class="o">=</span> <span class="n">datetime</span><span class="o">.</span><span class="n">time</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">run_daily</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">run_daily_c</span><span class="p">,</span> <span class="n">runtime</span><span class="p">)</span>
|
||
</code></pre>
|
||
</div>
|
||
<h4><a class="title-link" name="run_minutely" href="#run_minutely"></a> run_minutely()</h4>
|
||
|
||
<p>Execute a callback at the same time every minute. If the time has already passed, the function will not be invoked until the following minute at the specified time.</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="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_minutely</span><span class="p">(</span><span class="n">callback</span><span class="p">,</span> <span class="n">time</span> <span class="o">=</span> <span class="bp">None</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h4><a class="title-link" name="returns" href="#returns"></a> Returns</h4>
|
||
|
||
<p>A handle that can be used to cancel the timer.</p>
|
||
|
||
<h4><a class="title-link" name="parameters" href="#parameters"></a> Parameters</h4>
|
||
|
||
<h5><a class="title-link" name="callback" href="#callback"></a> callback</h5>
|
||
|
||
<p>Function to be invoked when the requested state change occurs. It must conform to the standard Scheduler Callback format documented above.</p>
|
||
|
||
<h5><a class="title-link" name="time" href="#time"></a> time</h5>
|
||
|
||
<p>A Python <code class="highlighter-rouge">time</code> object that specifies when the callback will occur, the hour and minute components of the time object are ignored. If the time specified is in the past, the callback will occur the next hour at the specified time. If time is not supplied, the callback will start a minute from the time that <code class="highlighter-rouge">run_minutely()</code> was executed.</p>
|
||
|
||
<h5><a class="title-link" name="kwargs" href="#kwargs"></a> **kwargs</h5>
|
||
|
||
<p>Arbitary keyword parameters to be provided to the callback function when it is invoked.</p>
|
||
|
||
<h4><a class="title-link" name="examples" href="#examples"></a> Examples</h4>
|
||
|
||
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="c"># Run Every Minute on the minute</span>
|
||
<span class="kn">import</span> <span class="nn">datetime</span>
|
||
<span class="o">...</span>
|
||
<span class="n">time</span> <span class="o">=</span> <span class="n">datetime</span><span class="o">.</span><span class="n">time</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">run_minutely</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">run_minutely_c</span><span class="p">,</span> <span class="n">time</span><span class="p">)</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h4><a class="title-link" name="run_every" href="#run_every"></a> run_every()</h4>
|
||
|
||
<p>Execute a repeating callback with a configurable delay starting at a specific time.</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="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_every</span><span class="p">(</span><span class="n">callback</span><span class="p">,</span> <span class="n">time</span><span class="p">,</span> <span class="n">repeat</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h4><a class="title-link" name="returns" href="#returns"></a> Returns</h4>
|
||
|
||
<p>A handle that can be used to cancel the timer.</p>
|
||
|
||
<h4><a class="title-link" name="parameters" href="#parameters"></a> Parameters</h4>
|
||
|
||
<h5><a class="title-link" name="callback" href="#callback"></a> callback</h5>
|
||
|
||
<p>Function to be invoked when the requested state change occurs. It must conform to the standard Scheduler Callback format documented above.</p>
|
||
|
||
<h5><a class="title-link" name="time" href="#time"></a> time</h5>
|
||
|
||
<p>A Python <code class="highlighter-rouge">time</code> object that specifies when the initial callback will occur.</p>
|
||
|
||
<h5><a class="title-link" name="repeat" href="#repeat"></a> repeat</h5>
|
||
|
||
<p>After the initial callback has occurred, another will occur every <code class="highlighter-rouge">repeat</code> seconds.</p>
|
||
|
||
<h5><a class="title-link" name="kwargs" href="#kwargs"></a> **kwargs</h5>
|
||
|
||
<p>Arbitary keyword parameters to be provided to the callback function when it is invoked.</p>
|
||
|
||
<h4><a class="title-link" name="examples" href="#examples"></a> Examples</h4>
|
||
|
||
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="c"># Run every 17 minutes starting in 2 hours time</span>
|
||
<span class="kn">import</span> <span class="nn">datetime</span>
|
||
<span class="o">...</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">run_every</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">run_every_c</span><span class="p">,</span> <span class="n">time</span><span class="p">,</span> <span class="mi">17</span> <span class="o">*</span> <span class="mi">60</span><span class="p">)</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h4><a class="title-link" name="cancel_timer" href="#cancel_timer"></a> cancel_timer()</h4>
|
||
<p>Cancel a previously created timer</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="bp">self</span><span class="o">.</span><span class="n">cancel_timer</span><span class="p">(</span><span class="n">handle</span><span class="p">)</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h4><a class="title-link" name="returns" href="#returns"></a> Returns</h4>
|
||
|
||
<p>None</p>
|
||
|
||
<h4><a class="title-link" name="parameters" href="#parameters"></a> Parameters</h4>
|
||
|
||
<h5><a class="title-link" name="handle" href="#handle"></a> handle</h5>
|
||
|
||
<p>A handle value returned from the original call to create the timer.</p>
|
||
|
||
<h4><a class="title-link" name="examples" href="#examples"></a> Examples</h4>
|
||
|
||
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="bp">self</span><span class="o">.</span><span class="n">cancel_timer</span><span class="p">(</span><span class="n">handle</span><span class="p">)</span>
|
||
</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>
|
||
|
||
<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>
|
||
</div>
|
||
|
||
<h4><a class="title-link" name="returns" href="#returns"></a> Returns</h4>
|
||
|
||
<p>time - datetime object representing the next time the callback will be fired</p>
|
||
|
||
<p>interval - repeat interval if applicable, <code class="highlighter-rouge">0</code> otherwise.</p>
|
||
|
||
<p>kwargs - the values supplied when the callback was initially created.</p>
|
||
|
||
<h4><a class="title-link" name="parameters" href="#parameters"></a> Parameters</h4>
|
||
|
||
<h5><a class="title-link" name="handle" href="#handle"></a> handle</h5>
|
||
|
||
<p>The handle returned when the scheduler call was made.</p>
|
||
|
||
<h4><a class="title-link" name="examples" href="#examples"></a> Examples</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>
|
||
</div>
|
||
|
||
<h3><a class="title-link" name="scheduler-ransomization" href="#scheduler-ransomization"></a> Scheduler Ransomization</h3>
|
||
|
||
<p>All of the scheduler calls above support 2 additional optional arguments, <code class="highlighter-rouge">random_start</code> and <code class="highlighter-rouge">random_end</code>. Using these arguments it is possible to randomize the firing of callbacks to the degree desired by setting the appropriate number of seconds with the parameters.</p>
|
||
|
||
<ul>
|
||
<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 whcih 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>
|
||
<span class="c"># Run a callback in 2 minutes plus a random number of seconds between 0 and 60, e.g. run between 120 and 180 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_end</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>
|
||
<span class="c"># Run a callback in 2 minutes plus or minus a random number of seconds between 0 and 60, e.g. run between 60 and 180 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="n">random_end</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>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h2><a class="title-link" name="sunrise-and-sunset" href="#sunrise-and-sunset"></a> Sunrise and Sunset</h2>
|
||
|
||
<p>AppDaemon has a number of features to allow easy tracking of sunrise and sunset as well as a couple of scheduler functions. Note that the scheduler functions also support the randomization parameters described above, but they cannot be used in conjunction with the <code class="highlighter-rouge">offset</code> parameter`.</p>
|
||
|
||
<h3><a class="title-link" name="run_at_sunrise" href="#run_at_sunrise"></a> run_at_sunrise()</h3>
|
||
|
||
<p>Run a callback at or around sunrise.</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="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_at_sunrise</span><span class="p">(</span><span class="n">callback</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h4><a class="title-link" name="returns" href="#returns"></a> Returns</h4>
|
||
|
||
<p>A handle that can be used to cancel the timer.</p>
|
||
|
||
<h4><a class="title-link" name="parameters" href="#parameters"></a> Parameters</h4>
|
||
|
||
<h5><a class="title-link" name="callback" href="#callback"></a> callback</h5>
|
||
|
||
<p>Function to be invoked when the requested state change occurs. It must conform to the standard Scheduler Callback format documented above.</p>
|
||
|
||
<h5><a class="title-link" name="offset--seconds" href="#offset--seconds"></a> offset = <seconds></seconds></h5>
|
||
|
||
<p>The time in seconds that the callback should be delayed after sunrise. A negative value will result in the callback occurring before sunrise. This parameter cannot be combined with <code class="highlighter-rouge">random_start</code> or <code class="highlighter-rouge">random_end</code></p>
|
||
|
||
<h5><a class="title-link" name="kwargs" href="#kwargs"></a> **kwargs</h5>
|
||
|
||
<p>Arbitary keyword parameters to be provided to the callback function when it is invoked.</p>
|
||
|
||
<h4><a class="title-link" name="examples" href="#examples"></a> Examples</h4>
|
||
|
||
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="kn">import</span> <span class="nn">datetime</span>
|
||
<span class="o">...</span>
|
||
<span class="c"># Run 45 minutes before sunset</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">run_at_sunrise</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">sun</span><span class="p">,</span> <span class="n">offset</span> <span class="o">=</span> <span class="n">datetime</span><span class="o">.</span><span class="n">timedelta</span><span class="p">(</span><span class="n">minutes</span> <span class="o">=</span> <span class="o">-</span><span class="mi">45</span><span class="p">)</span><span class="o">.</span><span class="n">total_seconds</span><span class="p">(),</span> <span class="s">"Sunrise -45 mins"</span><span class="p">)</span>
|
||
<span class="c"># or you can just do the math yourself</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">run_at_sunrise</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">sun</span><span class="p">,</span> <span class="n">offset</span> <span class="o">=</span> <span class="mi">30</span> <span class="o">*</span> <span class="mi">60</span><span class="p">,</span> <span class="s">"Sunrise +30 mins"</span><span class="p">)</span>
|
||
<span class="c"># Run at a random time +/- 60 minutes from sunrise</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">run_at_sunrise</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">sun</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="o">*</span><span class="mi">60</span><span class="p">,</span> <span class="n">random_end</span> <span class="o">=</span> <span class="mi">60</span><span class="o">*</span><span class="mi">60</span><span class="p">,</span> <span class="s">"Sunrise, random +/- 60 mins"</span><span class="p">)</span>
|
||
<span class="c"># Run at a random time between 30 and 60 minutes before sunrise</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">run_at_sunrise</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">sun</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="o">*</span><span class="mi">60</span><span class="p">,</span> <span class="n">random_end</span> <span class="o">=</span> <span class="mi">30</span><span class="o">*</span><span class="mi">60</span><span class="p">,</span> <span class="s">"Sunrise, random - 30 - 60 mins"</span><span class="p">)</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h3><a class="title-link" name="run_at_sunset" href="#run_at_sunset"></a> run_at_sunset()</h3>
|
||
|
||
<p>Run a callback at or around sunset.</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="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_at_sunset</span><span class="p">(</span><span class="n">callback</span><span class="p">,</span> <span class="n">offset</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h4><a class="title-link" name="returns" href="#returns"></a> Returns</h4>
|
||
|
||
<p>A handle that can be used to cancel the timer.</p>
|
||
|
||
<h4><a class="title-link" name="parameters" href="#parameters"></a> Parameters</h4>
|
||
|
||
<h5><a class="title-link" name="callback" href="#callback"></a> callback</h5>
|
||
|
||
<p>Function to be invoked when the requested state change occurs. It must conform to the standard Scheduler Callback format documented above.</p>
|
||
|
||
<h5><a class="title-link" name="offset--seconds" href="#offset--seconds"></a> offset = <seconds></seconds></h5>
|
||
|
||
<p>The time in seconds that the callback should be delayed after sunrise. A negative value will result in the callback occurring before sunrise. This parameter cannot be combined with <code class="highlighter-rouge">random_start</code> or <code class="highlighter-rouge">random_end</code></p>
|
||
|
||
<h5><a class="title-link" name="kwargs" href="#kwargs"></a> **kwargs</h5>
|
||
|
||
<p>Arbitary keyword parameters to be provided to the callback function when it is invoked.</p>
|
||
|
||
<h4><a class="title-link" name="examples" href="#examples"></a> Examples</h4>
|
||
|
||
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="c"># Example using timedelta</span>
|
||
<span class="kn">import</span> <span class="nn">datetime</span>
|
||
<span class="o">...</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">run_at_sunset</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">sun</span><span class="p">,</span> <span class="n">datetime</span><span class="o">.</span><span class="n">timedelta</span><span class="p">(</span><span class="n">minutes</span> <span class="o">=</span> <span class="o">-</span><span class="mi">45</span><span class="p">)</span><span class="o">.</span><span class="n">total_seconds</span><span class="p">(),</span> <span class="s">"Sunset -45 mins"</span><span class="p">)</span>
|
||
<span class="c"># or you can just do the math yourself</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">run_at_sunset</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">sun</span><span class="p">,</span> <span class="mi">30</span> <span class="o">*</span> <span class="mi">60</span><span class="p">,</span> <span class="s">"Sunset +30 mins"</span><span class="p">)</span>
|
||
<span class="c"># Run at a random time +/- 60 minutes from sunset</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">run_at_sunset</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">sun</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="o">*</span><span class="mi">60</span><span class="p">,</span> <span class="n">random_end</span> <span class="o">=</span> <span class="mi">60</span><span class="o">*</span><span class="mi">60</span><span class="p">,</span> <span class="s">"Sunset, random +/- 60 mins"</span><span class="p">)</span>
|
||
<span class="c"># Run at a random time between 30 and 60 minutes before sunset</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">run_at_sunset</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">sun</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="o">*</span><span class="mi">60</span><span class="p">,</span> <span class="n">random_end</span> <span class="o">=</span> <span class="mi">30</span><span class="o">*</span><span class="mi">60</span><span class="p">,</span> <span class="s">"Sunset, random - 30 - 60 mins"</span><span class="p">)</span>
|
||
</code></pre>
|
||
</div>
|
||
<h3><a class="title-link" name="sunrise" href="#sunrise"></a> sunrise()</h3>
|
||
|
||
<p>Return the time that the next Sunrise will occur.</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="bp">self</span><span class="o">.</span><span class="n">sunrise</span><span class="p">()</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h4><a class="title-link" name="returns" href="#returns"></a> Returns</h4>
|
||
|
||
<p>A Python datetime that represents the next time Sunrise will occur.</p>
|
||
|
||
<h4><a class="title-link" name="examples" href="#examples"></a> Examples</h4>
|
||
|
||
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="n">rise_time</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">sunrise</span><span class="p">()</span>
|
||
</code></pre>
|
||
</div>
|
||
<h3><a class="title-link" name="sunset" href="#sunset"></a> sunset()</h3>
|
||
|
||
<p>Return the time that the next Sunset will occur.</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="bp">self</span><span class="o">.</span><span class="n">sunset</span><span class="p">()</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h4><a class="title-link" name="returns" href="#returns"></a> Returns</h4>
|
||
|
||
<p>A Python datetime that represents the next time Sunset will occur.</p>
|
||
|
||
<h4><a class="title-link" name="examples" href="#examples"></a> Examples</h4>
|
||
|
||
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="n">set_time</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">sunset</span><span class="p">()</span>
|
||
</code></pre>
|
||
</div>
|
||
<h3><a class="title-link" name="sun_up" href="#sun_up"></a> sun_up()</h3>
|
||
|
||
<p>A function that allows you to determine if the sun is currently up.</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">result</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">sun_up</span><span class="p">()</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h4><a class="title-link" name="returns" href="#returns"></a> Returns</h4>
|
||
|
||
<p><code class="highlighter-rouge">True</code> if the sun is up, False otherwise.</p>
|
||
|
||
<h4><a class="title-link" name="examples" href="#examples"></a> Examples</h4>
|
||
|
||
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">sun_up</span><span class="p">():</span>
|
||
<span class="n">do</span> <span class="n">something</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h3><a class="title-link" name="sun_down" href="#sun_down"></a> sun_down()</h3>
|
||
|
||
<p>A function that allows you to determine if the sun is currently down.</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">result</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">sun_down</span><span class="p">()</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h4><a class="title-link" name="returns" href="#returns"></a> Returns</h4>
|
||
|
||
<p><code class="highlighter-rouge">True</code> if the sun is down, False otherwise.</p>
|
||
|
||
<h4><a class="title-link" name="examples" href="#examples"></a> Examples</h4>
|
||
|
||
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">sun_down</span><span class="p">():</span>
|
||
<span class="n">do</span> <span class="n">something</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h2><a class="title-link" name="calling-services" href="#calling-services"></a> Calling Services</h2>
|
||
|
||
<h3><a class="title-link" name="about-services" href="#about-services"></a> About Services</h3>
|
||
|
||
<p>Services within Home Assistant are how changes are made to the system and its devices. Services can be used to turn lights on and off, set thermostats and a whole number of other things. Home Assistant supplies a single interface to all these disparate services that take arbitrary parameters. AppDaemon provides the <code class="highlighter-rouge">call_service()</code> function to call into Home Assistant and run a service. In addition, it also provides convenience functions for some of the more common services making calling them a little easier.</p>
|
||
|
||
<h3><a class="title-link" name="call_service" href="#call_service"></a> call_service()</h3>
|
||
|
||
<p>Call service is the basic way of calling a service within AppDaemon. It can call any service and provide any required parameters. Available services can be found using the developer tools in the UI. For listed services, the part before the first period is the domain, and the part after is the service name. For instance, <code class="highlighter-rouge">light.turn_on</code> has a domain of <code class="highlighter-rouge">light</code> and a service name of <code class="highlighter-rouge">turn_on</code>.</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="bp">self</span><span class="o">.</span><span class="n">call_service</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">service</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h4><a class="title-link" name="returns" href="#returns"></a> Returns</h4>
|
||
|
||
<p>None</p>
|
||
|
||
<h4><a class="title-link" name="parameters" href="#parameters"></a> Parameters</h4>
|
||
|
||
<h5><a class="title-link" name="service" href="#service"></a> service</h5>
|
||
|
||
<p>The service name, e.g. <code class="highlighter-rouge">light.turn_on</code>.</p>
|
||
|
||
<h5><a class="title-link" name="kwargs" href="#kwargs"></a> **kwargs</h5>
|
||
|
||
<p>Each service has different parameter requirements. This argument allows you to specify a comma separated list of keyword value pairs, e.g. <code class="highlighter-rouge">entity_id = light.office_1</code>. These parameters will be different for every service and can be discovered using the developer tools. Most if not all service calls require an <code class="highlighter-rouge">entity_id</code> however, so use of the above example is very common with this call.</p>
|
||
|
||
<h4><a class="title-link" name="examples" href="#examples"></a> Examples</h4>
|
||
|
||
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="bp">self</span><span class="o">.</span><span class="n">call_service</span><span class="p">(</span><span class="s">"light/turn_on"</span><span class="p">,</span> <span class="n">entity_id</span> <span class="o">=</span> <span class="s">"light.office_lamp"</span><span class="p">,</span> <span class="n">color_name</span> <span class="o">=</span> <span class="s">"red"</span><span class="p">)</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">call_service</span><span class="p">(</span><span class="s">"notify/notify"</span><span class="p">,</span> <span class="n">title</span> <span class="o">=</span> <span class="s">"Hello"</span><span class="p">,</span> <span class="n">message</span> <span class="o">=</span> <span class="s">"Hello World"</span><span class="p">)</span>
|
||
</code></pre>
|
||
</div>
|
||
<h3><a class="title-link" name="turn_on" href="#turn_on"></a> turn_on()</h3>
|
||
|
||
<p>This is a convenience function for the <code class="highlighter-rouge">homassistant.turn_on</code> function. It is able to turn on pretty much anything in Home Assistant that can be turned on or run:</p>
|
||
|
||
<ul>
|
||
<li>Lights</li>
|
||
<li>Switches</li>
|
||
<li>Scenes</li>
|
||
<li>Scripts</li>
|
||
</ul>
|
||
|
||
<p>And many more.</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="bp">self</span><span class="o">.</span><span class="n">turn_on</span><span class="p">(</span><span class="n">entity_id</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h4><a class="title-link" name="returns" href="#returns"></a> Returns</h4>
|
||
|
||
<p>None</p>
|
||
|
||
<h4><a class="title-link" name="parameters" href="#parameters"></a> Parameters</h4>
|
||
|
||
<h5><a class="title-link" name="entity_id" href="#entity_id"></a> entity_id</h5>
|
||
|
||
<p>Fully qualified entity_id of the thing to be turned on, e.g. <code class="highlighter-rouge">light.office_lamp</code> or <code class="highlighter-rouge">scene.downstairs_on</code></p>
|
||
|
||
<h5><a class="title-link" name="kwargs" href="#kwargs"></a> **kwargs</h5>
|
||
|
||
<p>A comma separated list of key value pairs to allow specification of parameters over and above <code class="highlighter-rouge">entity_id</code>.</p>
|
||
|
||
<h4><a class="title-link" name="examples" href="#examples"></a> Examples</h4>
|
||
|
||
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="bp">self</span><span class="o">.</span><span class="n">turn_on</span><span class="p">(</span><span class="s">"switch.patio_lights"</span><span class="p">)</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">turn_on</span><span class="p">(</span><span class="s">"scene.bedrrom_on"</span><span class="p">)</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">turn_on</span><span class="p">(</span><span class="s">"light.office_1"</span><span class="p">,</span> <span class="n">color_name</span> <span class="o">=</span> <span class="s">"green"</span><span class="p">)</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h3><a class="title-link" name="turn_off" href="#turn_off"></a> turn_off()</h3>
|
||
|
||
<p>This is a convenience function for the <code class="highlighter-rouge">homassistant.turn_off</code> function. Like <code class="highlighter-rouge">homeassistant.turn_on</code>, it is able to turn off pretty much anything in Home Assistant that can be turned off.</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="bp">self</span><span class="o">.</span><span class="n">turn_off</span><span class="p">(</span><span class="n">entity_id</span><span class="p">)</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h4><a class="title-link" name="returns" href="#returns"></a> Returns</h4>
|
||
|
||
<p>None</p>
|
||
|
||
<h4><a class="title-link" name="parameters" href="#parameters"></a> Parameters</h4>
|
||
|
||
<h5><a class="title-link" name="entity_id" href="#entity_id"></a> entity_id</h5>
|
||
|
||
<p>Fully qualified entity_id of the thing to be turned off, e.g. <code class="highlighter-rouge">light.office_lamp</code> or <code class="highlighter-rouge">scene.downstairs_on</code>.</p>
|
||
|
||
<h4><a class="title-link" name="examples" href="#examples"></a> Examples</h4>
|
||
|
||
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="bp">self</span><span class="o">.</span><span class="n">turn_off</span><span class="p">(</span><span class="s">"switch.patio_lights"</span><span class="p">)</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">turn_off</span><span class="p">(</span><span class="s">"light.office_1"</span><span class="p">)</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h3><a class="title-link" name="toggle" href="#toggle"></a> toggle()</h3>
|
||
|
||
<p>This is a convenience function for the <code class="highlighter-rouge">homassistant.toggle</code> function. It is able to flip the state of pretty much anything in Home Assistant that can be turned on or off.</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="bp">self</span><span class="o">.</span><span class="n">toggle</span><span class="p">(</span><span class="n">entity_id</span><span class="p">)</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h4><a class="title-link" name="returns" href="#returns"></a> Returns</h4>
|
||
|
||
<p>None</p>
|
||
|
||
<h4><a class="title-link" name="parameters" href="#parameters"></a> Parameters</h4>
|
||
|
||
<h5><a class="title-link" name="entity_id" href="#entity_id"></a> entity_id</h5>
|
||
|
||
<p>Fully qualified entity_id of the thing to be toggled, e.g. <code class="highlighter-rouge">light.office_lamp</code> or <code class="highlighter-rouge">scene.downstairs_on</code>.</p>
|
||
|
||
<h4><a class="title-link" name="examples" href="#examples"></a> Examples</h4>
|
||
|
||
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="bp">self</span><span class="o">.</span><span class="n">toggle</span><span class="p">(</span><span class="s">"switch.patio_lights"</span><span class="p">)</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">toggle</span><span class="p">(</span><span class="s">"light.office_1"</span><span class="p">,</span> <span class="n">color_name</span> <span class="o">=</span> <span class="s">"green"</span><span class="p">)</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h3><a class="title-link" name="select_value" href="#select_value"></a> select_value()</h3>
|
||
|
||
<p>This is a convenience function for the <code class="highlighter-rouge">input_slider.select_value</code> function. It is able to set the value of an input_slider in Home Assistant.</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="bp">self</span><span class="o">.</span><span class="n">select_value</span><span class="p">(</span><span class="n">entity_id</span><span class="p">,</span> <span class="n">value</span><span class="p">)</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h4><a class="title-link" name="returns" href="#returns"></a> Returns</h4>
|
||
|
||
<p>None</p>
|
||
|
||
<h4><a class="title-link" name="parameters" href="#parameters"></a> Parameters</h4>
|
||
|
||
<h5><a class="title-link" name="entity_id" href="#entity_id"></a> entity_id</h5>
|
||
|
||
<p>Fully qualified entity_id of the input_slider to be changed, e.g. <code class="highlighter-rouge">input_slider.alarm_hour</code>.</p>
|
||
|
||
<h5><a class="title-link" name="value" href="#value"></a> value</h5>
|
||
|
||
<p>The new value to set the input slider to.</p>
|
||
|
||
<h4><a class="title-link" name="examples" href="#examples"></a> Examples</h4>
|
||
|
||
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="bp">self</span><span class="o">.</span><span class="n">select_value</span><span class="p">(</span><span class="s">"input_slider.alarm_hour"</span><span class="p">,</span> <span class="mi">6</span><span class="p">)</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h3><a class="title-link" name="select_option" href="#select_option"></a> select_option()</h3>
|
||
|
||
<p>This is a convenience function for the <code class="highlighter-rouge">input_select.select_option</code> function. It is able to set the value of an input_select in Home Assistant.</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="bp">self</span><span class="o">.</span><span class="n">select_option</span><span class="p">(</span><span class="n">entity_id</span><span class="p">,</span> <span class="n">option</span><span class="p">)</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h4><a class="title-link" name="returns" href="#returns"></a> Returns</h4>
|
||
|
||
<p>None</p>
|
||
|
||
<h4><a class="title-link" name="parameters" href="#parameters"></a> Parameters</h4>
|
||
|
||
<h5><a class="title-link" name="entity_id" href="#entity_id"></a> entity_id</h5>
|
||
|
||
<p>Fully qualified entity_id of the input_select to be changed, e.g. <code class="highlighter-rouge">input_select.mode</code>.</p>
|
||
|
||
<h5><a class="title-link" name="value" href="#value"></a> value</h5>
|
||
|
||
<p>The new value to set the input slider to.</p>
|
||
|
||
<h4><a class="title-link" name="examples" href="#examples"></a> Examples</h4>
|
||
|
||
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="bp">self</span><span class="o">.</span><span class="n">select_option</span><span class="p">(</span><span class="s">"input_select.mode"</span><span class="p">,</span> <span class="s">"Day"</span><span class="p">)</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h3><a class="title-link" name="notify" href="#notify"></a> notify()</h3>
|
||
|
||
<p>This is a convenience function for the <code class="highlighter-rouge">notify.notify</code> service. It will send a notification to your defualt notification service. If you have more than one, use <code class="highlighter-rouge">call_service()</code> to call the specific notification service you require instead.</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">notify</span><span class="p">(</span><span class="n">message</span><span class="p">,</span> <span class="n">title</span><span class="o">=</span><span class="bp">None</span><span class="p">)</span>
|
||
</code></pre>
|
||
</div>
|
||
<h4><a class="title-link" name="returns" href="#returns"></a> Returns</h4>
|
||
|
||
<p>None</p>
|
||
|
||
<h4><a class="title-link" name="parameters" href="#parameters"></a> Parameters</h4>
|
||
|
||
<h5><a class="title-link" name="message" href="#message"></a> message</h5>
|
||
|
||
<p>Message to be sent to the notification service.</p>
|
||
|
||
<h5><a class="title-link" name="title" href="#title"></a> title</h5>
|
||
|
||
<p>Title of the notification - optional.</p>
|
||
|
||
<h4><a class="title-link" name="examples" href="#examples"></a> Examples</h4>
|
||
|
||
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="bp">self</span><span class="o">.</span><span class="n">notify</span><span class="p">(</span><span class="s">""</span><span class="p">,</span> <span class="s">"Switching mode to Evening"</span><span class="p">)</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h2><a class="title-link" name="events" href="#events"></a> Events</h2>
|
||
|
||
<h3><a class="title-link" name="about-events" href="#about-events"></a> About Events</h3>
|
||
|
||
<p>Events are a fundamental part of how Home Assistant works under the covers. HA has an event bus that all components can read and write to, enabling components to inform other components when important events take place. We have already seen how state changes can be propagated to AppDaemon - a state change however is merely an example of an event within Home Assistant. There are several other event types, among them are:</p>
|
||
|
||
<ul>
|
||
<li><code class="highlighter-rouge">homeassistant_start</code></li>
|
||
<li><code class="highlighter-rouge">homeassistant_stop</code></li>
|
||
<li><code class="highlighter-rouge">state_changed</code></li>
|
||
<li><code class="highlighter-rouge">service_registered</code></li>
|
||
<li><code class="highlighter-rouge">call_service</code></li>
|
||
<li><code class="highlighter-rouge">service_executed</code></li>
|
||
<li><code class="highlighter-rouge">platform_discovered</code></li>
|
||
<li><code class="highlighter-rouge">component_loaded</code></li>
|
||
</ul>
|
||
|
||
<p>Using AppDaemon, it is possible to subscribe to specific events as well as fire off events.</p>
|
||
|
||
<p>In addition to the Home Assistant supplied events, AppDaemon adds 2 more events. These are internal to AppDaemon and are not visible on the Home Assistant bus:</p>
|
||
|
||
<ul>
|
||
<li><code class="highlighter-rouge">appd_started</code> - fired once when AppDaemon is first started and after Apps are initialized</li>
|
||
<li><code class="highlighter-rouge">ha_started</code> - fired every time AppDaemon detects a Home Assistant restart</li>
|
||
</ul>
|
||
|
||
<h3><a class="title-link" name="about-event-callbacks" href="#about-event-callbacks"></a> About Event Callbacks</h3>
|
||
|
||
<p>As with State Change and Scheduler callbacks, Event Callbacks expect to call into functions with a known and specific signature and a class defined Scheduler callback function should look like this:</p>
|
||
|
||
<div class="language-python highlighter-rouge"><pre class="highlight"><code> <span class="k">def</span> <span class="nf">my_callback</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">event_name</span><span class="p">,</span> <span class="n">data</span><span class="p">,</span> <span class="n">kwargs</span><span class="p">):</span>
|
||
<span class="o"><</span><span class="n">do</span> <span class="n">some</span> <span class="n">useful</span> <span class="n">work</span> <span class="n">here</span><span class="o">></span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<p>You can call the function whatever you like - you will reference it in the Scheduler call, and you can create as many callback functions as you need.</p>
|
||
|
||
<p>The parameters have the following meanings:</p>
|
||
|
||
<h4><a class="title-link" name="self" href="#self"></a> self</h4>
|
||
|
||
<p>A standard Python object reference.</p>
|
||
|
||
<h4><a class="title-link" name="event_name" href="#event_name"></a> event_name</h4>
|
||
|
||
<p>Name of the event that was called, e.g. <code class="highlighter-rouge">call_service</code>.</p>
|
||
|
||
<h4><a class="title-link" name="data" href="#data"></a> data</h4>
|
||
|
||
<p>Any data that the system supplied with the event as a dict.</p>
|
||
|
||
<h4><a class="title-link" name="kwargs" href="#kwargs"></a> kwargs</h4>
|
||
|
||
<p>A dictionary containing Zero or more user keyword arguments to be supplied to the callback.</p>
|
||
|
||
<h3><a class="title-link" name="listen_event" href="#listen_event"></a> listen_event()</h3>
|
||
|
||
<p>Listen event sets up a callback for a specific event, or any event.</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">handle</span> <span class="o">=</span> <span class="n">listen_event</span><span class="p">(</span><span class="n">function</span><span class="p">,</span> <span class="n">event</span> <span class="o">=</span> <span class="bp">None</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
|
||
</code></pre>
|
||
</div>
|
||
<h4><a class="title-link" name="returns" href="#returns"></a> Returns</h4>
|
||
|
||
<p>A handle that can be used to cancel the callback.</p>
|
||
|
||
<h4><a class="title-link" name="parameters" href="#parameters"></a> Parameters</h4>
|
||
|
||
<h5><a class="title-link" name="function" href="#function"></a> function</h5>
|
||
|
||
<p>The function to be called when the event is fired.</p>
|
||
|
||
<h5><a class="title-link" name="event" href="#event"></a> event</h5>
|
||
|
||
<p>Name of the event to subscribe to. Can be a standard Home Assistant event such as <code class="highlighter-rouge">service_registered</code> or an arbitrary custom event such as <code class="highlighter-rouge">"MODE_CHANGE"</code>. If no event is specified, <code class="highlighter-rouge">listen_event()</code> will subscribe to all events.</p>
|
||
|
||
<h5><a class="title-link" name="kwargs-optional" href="#kwargs-optional"></a> **kwargs (optional)</h5>
|
||
|
||
<p>One or more keyword value pairs representing App specific parameters to supply to the callback. If the keywords match values within the event data, they will act as filters, meaning that if they don’t match the values, the callback will not fire.</p>
|
||
|
||
<p>As an example of this, a Minimote controller when activated will generate an event called <code class="highlighter-rouge">zwave.scene_activated</code>, along with 2 pieces of data that are specific to the event - <code class="highlighter-rouge">entity_id</code> and <code class="highlighter-rouge">scene</code>. If you include keyword values for either of those, the values supplied to the `listen_event()1 call must match the values in the event or it will not fire. If the keywords do not match any of the data in the event they are simply ignored.</p>
|
||
|
||
<p>Filtering will work with any event type, but it will be necessary to figure out the data associated with the event to understand what values can be filtered on. This can be achieved by examining Home Assistant’s logfiles when the event fires.</p>
|
||
|
||
<h4><a class="title-link" name="examples" href="#examples"></a> Examples</h4>
|
||
|
||
<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>
|
||
<span class="c"># Listen for a minimote event activating scene 3:</span>
|
||
<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">generic_event</span><span class="p">,</span> <span class="s">"zwave.scene_activated"</span><span class="p">,</span> <span class="n">scene_id</span> <span class="o">=</span> <span class="mi">3</span><span class="p">)</span>
|
||
<span class="c"># Listen for a minimote event activating scene 3 from a specific minimote:</span>
|
||
<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">generic_event</span><span class="p">,</span> <span class="s">"zwave.scene_activated"</span><span class="p">,</span> <span class="n">entity_id</span> <span class="o">=</span> <span class="s">"minimote_31"</span><span class="p">,</span> <span class="n">scene_id</span> <span class="o">=</span> <span class="mi">3</span><span class="p">)</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h3><a class="title-link" name="cancel_listen_event" href="#cancel_listen_event"></a> cancel_listen_event()</h3>
|
||
|
||
<p>Cancels callbacks for a specific event.</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">cancel_listen_event</span><span class="p">(</span><span class="n">handle</span><span class="p">)</span>
|
||
</code></pre>
|
||
</div>
|
||
<h4><a class="title-link" name="returns" href="#returns"></a> Returns</h4>
|
||
|
||
<p>None.</p>
|
||
|
||
<h4><a class="title-link" name="parameters" href="#parameters"></a> Parameters</h4>
|
||
|
||
<h5>handle</h5>
|
||
|
||
<p>A handle returned from a previous call to <code class="highlighter-rouge">listen_event()</code>.</p>
|
||
|
||
<h4><a class="title-link" name="examples" href="#examples"></a> Examples</h4>
|
||
|
||
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="bp">self</span><span class="o">.</span><span class="n">cancel_listen_event</span><span class="p">(</span><span class="n">handle</span><span class="p">)</span>
|
||
</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>
|
||
|
||
<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>
|
||
</div>
|
||
|
||
<h4><a class="title-link" name="returns" href="#returns"></a> Returns</h4>
|
||
|
||
<p>service, kwargs - the values supplied when the callback was initially created.</p>
|
||
|
||
<h4><a class="title-link" name="parameters" href="#parameters"></a> Parameters</h4>
|
||
|
||
<h5><a class="title-link" name="handle" href="#handle"></a> handle</h5>
|
||
|
||
<p>The handle returned when the <code class="highlighter-rouge">listen_event()</code> call was made.</p>
|
||
|
||
<h4><a class="title-link" name="examples" href="#examples"></a> Examples</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>
|
||
</div>
|
||
|
||
<h3><a class="title-link" name="fire_event" href="#fire_event"></a> fire_event()</h3>
|
||
|
||
<p>Fire an event on the HomeAssistant bus, for other components to hear.</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">fire_event</span><span class="p">(</span><span class="n">event</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h4><a class="title-link" name="returns" href="#returns"></a> Returns</h4>
|
||
|
||
<p>None.</p>
|
||
|
||
<h4><a class="title-link" name="parameters" href="#parameters"></a> Parameters</h4>
|
||
|
||
<h5><a class="title-link" name="event" href="#event"></a> event</h5>
|
||
|
||
<p>Name of the event. Can be a standard Home Assistant event such as <code class="highlighter-rouge">service_registered</code> or an arbitrary custom event such as <code class="highlighter-rouge">"MODE_CHANGE"</code>.</p>
|
||
|
||
<h5><a class="title-link" name="kwargs" href="#kwargs"></a> **kwargs</h5>
|
||
|
||
<p>Zero or more keyword arguments that will be supplied as part of the event.</p>
|
||
|
||
<h4><a class="title-link" name="examples" href="#examples"></a> Examples</h4>
|
||
|
||
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="bp">self</span><span class="o">.</span><span class="n">fire_event</span><span class="p">(</span><span class="s">"MY_CUSTOM_EVENT"</span><span class="p">,</span> <span class="n">jam</span><span class="o">=</span><span class="s">"true"</span><span class="p">)</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h3><a class="title-link" name="event-callback-function-signature" href="#event-callback-function-signature"></a> Event Callback Function Signature</h3>
|
||
|
||
<p>Functions called as an event callback will be supplied with 2 arguments:</p>
|
||
|
||
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="k">def</span> <span class="nf">service</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">event_name</span><span class="p">,</span> <span class="n">data</span><span class="p">):</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h4><a class="title-link" name="event_name" href="#event_name"></a> event_name</h4>
|
||
|
||
<p>The name of the event that caused the callback, e.g. <code class="highlighter-rouge">"MODE_CHANGE"</code> or <code class="highlighter-rouge">call_service</code>.</p>
|
||
|
||
<h4><a class="title-link" name="data" href="#data"></a> data</h4>
|
||
|
||
<p>A dictionary containing any additional information associated with the event.</p>
|
||
|
||
<h3><a class="title-link" name="use-of-events-for-signalling-between-home-assistant-and-appdaemon" href="#use-of-events-for-signalling-between-home-assistant-and-appdaemon"></a> Use of Events for Signalling between Home Assistant and AppDaemon</h3>
|
||
|
||
<p>Home Assistant allows for the creation of custom events and existing components can send and receive them. This provides a useful mechanism for signaling back and forth between Home Assistant and AppDaemon. For instance, if you would like to create a UI Element to fire off some code in Home Assistant, all that is necessary is to create a script to fire a custom event, then subscribe to that event in AppDaemon. The script would look something like this:</p>
|
||
|
||
<div class="language-yaml highlighter-rouge"><pre class="highlight"><code><span class="s">alias</span><span class="pi">:</span> <span class="s">Day</span>
|
||
<span class="s">sequence</span><span class="pi">:</span>
|
||
<span class="pi">-</span> <span class="s">event</span><span class="pi">:</span> <span class="s">MODE_CHANGE</span>
|
||
<span class="s">event_data</span><span class="pi">:</span>
|
||
<span class="s">mode</span><span class="pi">:</span> <span class="s">Day</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<p>The custom event <code class="highlighter-rouge">MODE_CHANGE</code> would be subscribed to with:</p>
|
||
|
||
<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>
|
||
|
||
<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>
|
||
<span class="s">event_type</span><span class="pi">:</span> <span class="s">MODE_CHANGE</span>
|
||
<span class="s">...</span>
|
||
<span class="s">...</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<p>This can be triggered with a call to AppDaemon’s fire_event() as follows:</p>
|
||
|
||
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="bp">self</span><span class="o">.</span><span class="n">fire_event</span><span class="p">(</span><span class="s">"MODE_CHANGE"</span><span class="p">,</span> <span class="n">mode</span> <span class="o">=</span> <span class="s">"Day"</span><span class="p">)</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h2><a class="title-link" name="presence" href="#presence"></a> Presence</h2>
|
||
|
||
<p>Presence in Home Assistant is tracked using Device Trackers. The state of all device trackers can be found using the <code class="highlighter-rouge">get_state()</code> call, however AppDaemon provides several convenience functions to make this easier.</p>
|
||
|
||
<h3><a class="title-link" name="get_trackers" href="#get_trackers"></a> get_trackers()</h3>
|
||
|
||
<p>Return a list of all device trackers. This is designed to be iterated over.</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">tracker_list</span> <span class="o">=</span> <span class="n">get_trackers</span><span class="p">()</span>
|
||
</code></pre>
|
||
</div>
|
||
<h4><a class="title-link" name="returns" href="#returns"></a> Returns</h4>
|
||
|
||
<p>An iterable list of all device trackers.</p>
|
||
|
||
<h4><a class="title-link" name="examples" href="#examples"></a> Examples</h4>
|
||
|
||
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="n">trackers</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">get_trackers</span><span class="p">()</span>
|
||
<span class="k">for</span> <span class="n">tracker</span> <span class="ow">in</span> <span class="n">trackers</span><span class="p">:</span>
|
||
<span class="n">do</span> <span class="n">something</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h3><a class="title-link" name="get_tracker_state" href="#get_tracker_state"></a> get_tracker_state()</h3>
|
||
|
||
<p>Get the state of a tracker. The values returned depend in part on the configuration and type of device trackers in the system. Simpler tracker types like <code class="highlighter-rouge">Locative</code> or <code class="highlighter-rouge">NMAP</code> will return one of 2 states:</p>
|
||
|
||
<ul>
|
||
<li><code class="highlighter-rouge">home</code></li>
|
||
<li><code class="highlighter-rouge">not_home</code></li>
|
||
</ul>
|
||
|
||
<p>Some types of device tracker are in addition able to supply locations that have been configured as Geofences, in which case the name of that location can be returned.</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">location</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">get_tracker_state</span><span class="p">(</span><span class="n">tracker_id</span><span class="p">)</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h4><a class="title-link" name="returns" href="#returns"></a> Returns</h4>
|
||
|
||
<p>A string representing the location of the tracker.</p>
|
||
|
||
<h4><a class="title-link" name="parameters" href="#parameters"></a> Parameters</h4>
|
||
|
||
<h5><a class="title-link" name="tracker_id" href="#tracker_id"></a> tracker_id</h5>
|
||
|
||
<p>Fully qualified entity_id of the device tracker to query, e.g. <code class="highlighter-rouge">device_tracker.andrew</code>.</p>
|
||
|
||
<h4><a class="title-link" name="examples" href="#examples"></a> Examples</h4>
|
||
|
||
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="n">trackers</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">get_trackers</span><span class="p">()</span>
|
||
<span class="k">for</span> <span class="n">tracker</span> <span class="ow">in</span> <span class="n">trackers</span><span class="p">:</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">log</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">tracker</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">get_tracker_state</span><span class="p">(</span><span class="n">tracker</span><span class="p">)))</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h3><a class="title-link" name="everyone_home" href="#everyone_home"></a> everyone_home()</h3>
|
||
|
||
<p>A convenience function to determine if everyone is home. Use this in preference to getting the state of <code class="highlighter-rouge">group.all_devices()</code> as it avoids a race condition when using state change callbacks for device trackers.</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">result</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">everyone_home</span><span class="p">()</span>
|
||
</code></pre>
|
||
</div>
|
||
<h4><a class="title-link" name="returns" href="#returns"></a> Returns</h4>
|
||
|
||
<p>Returns <code class="highlighter-rouge">True</code> if everyone is at home, <code class="highlighter-rouge">False</code> otherwise.</p>
|
||
|
||
<h4><a class="title-link" name="examples" href="#examples"></a> Examples</h4>
|
||
|
||
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">everyone_home</span><span class="p">():</span>
|
||
<span class="n">do</span> <span class="n">something</span>
|
||
</code></pre>
|
||
</div>
|
||
<h3><a class="title-link" name="anyone_home" href="#anyone_home"></a> anyone_home()</h3>
|
||
|
||
<p>A convenience function to determine if one or more person is home. Use this in preference to getting the state of <code class="highlighter-rouge">group.all_devices()</code> as it avoids a race condition when using state change callbacks for device trackers.</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">result</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">anyone_home</span><span class="p">()</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h4><a class="title-link" name="returns" href="#returns"></a> Returns</h4>
|
||
|
||
<p>Returns <code class="highlighter-rouge">True</code> if anyone is at home, <code class="highlighter-rouge">False</code> otherwise.</p>
|
||
|
||
<h4><a class="title-link" name="examples" href="#examples"></a> Examples</h4>
|
||
|
||
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">anyone_home</span><span class="p">():</span>
|
||
<span class="n">do</span> <span class="n">something</span>
|
||
</code></pre>
|
||
</div>
|
||
<h3><a class="title-link" name="noone_home" href="#noone_home"></a> noone_home()</h3>
|
||
|
||
<p>A convenience function to determine if no people are at home. Use this in preference to getting the state of group.all_devices() as it avoids a race condition when using state change callbacks for device trackers.</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">result</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">noone_home</span><span class="p">()</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h4><a class="title-link" name="returns" href="#returns"></a> Returns</h4>
|
||
|
||
<p>Returns <code class="highlighter-rouge">True</code> if no one is home, <code class="highlighter-rouge">False</code> otherwise.</p>
|
||
|
||
<h4><a class="title-link" name="examples" href="#examples"></a> Examples</h4>
|
||
|
||
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">noone_home</span><span class="p">():</span>
|
||
<span class="n">do</span> <span class="n">something</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h2><a class="title-link" name="miscellaneous-helper-functions" href="#miscellaneous-helper-functions"></a> Miscellaneous Helper Functions</h2>
|
||
|
||
<h3><a class="title-link" name="time" href="#time"></a> time()</h3>
|
||
|
||
<p>Returns a python <code class="highlighter-rouge">time</code> object representing the current time. Use this in preference to the standard Python ways to discover the current time, especially when using the “Time Travel” feature for testing.</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>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h4><a class="title-link" name="returns" href="#returns"></a> Returns</h4>
|
||
|
||
<p>A localised Python time object representing the current AppDaemon time.</p>
|
||
|
||
<h4><a class="title-link" name="parameters" href="#parameters"></a> Parameters</h4>
|
||
|
||
<p>None</p>
|
||
|
||
<h4><a class="title-link" name="example" href="#example"></a> Example</h4>
|
||
|
||
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="n">now</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">time</span><span class="p">()</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h3><a class="title-link" name="date" href="#date"></a> date()</h3>
|
||
|
||
<p>Returns a python <code class="highlighter-rouge">date</code> object representing the current date. Use this in preference to the standard Python ways to discover the current date, especially when using the “Time Travel” feature for testing.</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">date</span><span class="p">()</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h4><a class="title-link" name="returns" href="#returns"></a> Returns</h4>
|
||
|
||
<p>A localised Python time object representing the current AppDaemon date.</p>
|
||
|
||
<h4><a class="title-link" name="parameters" href="#parameters"></a> Parameters</h4>
|
||
|
||
<p>None</p>
|
||
|
||
<h4><a class="title-link" name="example" href="#example"></a> Example</h4>
|
||
|
||
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="n">today</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">date</span><span class="p">()</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h3><a class="title-link" name="datetime" href="#datetime"></a> datetime()</h3>
|
||
|
||
<p>Returns a python <code class="highlighter-rouge">datetime</code> object representing the current date and time. Use this in preference to the standard Python ways to discover the current time, especially when using the “Time Travel” feature for testing.</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">datetime</span><span class="p">()</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h4><a class="title-link" name="returns" href="#returns"></a> Returns</h4>
|
||
|
||
<p>A localised Python datetime object representing the current AppDaemon date and time.</p>
|
||
|
||
<h4><a class="title-link" name="parameters" href="#parameters"></a> Parameters</h4>
|
||
|
||
<p>None</p>
|
||
|
||
<h4><a class="title-link" name="example" href="#example"></a> Example</h4>
|
||
|
||
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="n">now</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">datetime</span><span class="p">()</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h3><a class="title-link" name="convert_utc" href="#convert_utc"></a> convert_utc()</h3>
|
||
|
||
<p>Home Assistant provides timestamps of several different sorts that may be used to gain additional insight into state changes. These timestamps are in UTC and are coded as ISO 8601 Combined date and time strings. <code class="highlighter-rouge">convert_utc()</code> will accept one of these strings and convert it to a localised Python datetime object representing the timestamp</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">convert_utc</span><span class="p">(</span><span class="n">utc_string</span><span class="p">)</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h4><a class="title-link" name="returns" href="#returns"></a> Returns</h4>
|
||
|
||
<p><code class="highlighter-rouge">convert_utc(utc_string)</code> returns a localised Python datetime object representing the timestamp.</p>
|
||
|
||
<h4><a class="title-link" name="parameters" href="#parameters"></a> Parameters</h4>
|
||
|
||
<h5><a class="title-link" name="utc_string" href="#utc_string"></a> utc_string</h5>
|
||
|
||
<p>An ISO 8601 encoded date and time string in the following format: <code class="highlighter-rouge">2016-07-13T14:24:02.040658-04:00</code></p>
|
||
|
||
<h4><a class="title-link" name="example" href="#example"></a> Example</h4>
|
||
|
||
<p>###<a class="title-link" name="parse_time" href="#parse_time"></a> parse_time()</p>
|
||
|
||
<p>Takes a string representation of a time, or sunrise or sunset offset and converts it to a <code class="highlighter-rouge">datetime.time</code> object.</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">parse_time</span><span class="p">(</span><span class="n">time_string</span><span class="p">)</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h4><a class="title-link" name="returns" href="#returns"></a> Returns</h4>
|
||
|
||
<p>A <code class="highlighter-rouge">datetime.time</code> object, representing the time given in the <code class="highlighter-rouge">time_string</code> argument.</p>
|
||
|
||
<h4><a class="title-link" name="parameters" href="#parameters"></a> Parameters</h4>
|
||
|
||
<h5><a class="title-link" name="time_string" href="#time_string"></a> time_string</h5>
|
||
|
||
<p>A representation of the time in a string format with one of the following formats:</p>
|
||
|
||
<ul>
|
||
<li>HH:MM:SS - the time in Hours Minutes and Seconds, 24 hour format.</li>
|
||
<li>sunrise | sunset [+ | - HH:MM:SS]- time of the next sunrise or sunset with an optional positive or negative offset in Hours Minutes and seconds</li>
|
||
</ul>
|
||
|
||
<h4><a class="title-link" name="example" href="#example"></a> Example</h4>
|
||
|
||
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="n">time</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">parse_time</span><span class="p">(</span><span class="s">"17:30:00"</span><span class="p">)</span>
|
||
<span class="n">time</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">parse_time</span><span class="p">(</span><span class="s">"sunrise"</span><span class="p">)</span>
|
||
<span class="n">time</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">parse_time</span><span class="p">(</span><span class="s">"sunset + 00:30:00"</span><span class="p">)</span>
|
||
<span class="n">time</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">parse_time</span><span class="p">(</span><span class="s">"sunrise + 01:00:00"</span><span class="p">)</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h3><a class="title-link" name="now_is_between" href="#now_is_between"></a> now_is_between()</h3>
|
||
|
||
<p>Takes two string representations of a time, or sunrise or sunset offset and returns true if the current time is between those 2 times. <code class="highlighter-rouge">now_is_between()</code> can correctly handle transitions across midnight.</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">now_is_between</span><span class="p">(</span><span class="n">start_time_string</span><span class="p">,</span> <span class="n">end_time_string</span><span class="p">)</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h4><a class="title-link" name="returns" href="#returns"></a> Returns</h4>
|
||
|
||
<p><code class="highlighter-rouge">True</code> if the current time is within the specified start and end times, <code class="highlighter-rouge">False</code> otherwise.</p>
|
||
|
||
<h4><a class="title-link" name="parameters" href="#parameters"></a> Parameters</h4>
|
||
|
||
<h5><a class="title-link" name="start_time_string-end_time_string" href="#start_time_string-end_time_string"></a> start_time_string, end_time_string</h5>
|
||
|
||
<p>A representation of the start and end time respectively in a string format with one of the following formats:</p>
|
||
|
||
<ul>
|
||
<li>HH:MM:SS - the time in Hours Minutes and Seconds, 24 hour format.</li>
|
||
<li>sunrise | sunset [+ | - HH:MM:SS]- time of the next sunrise or sunset with an optional positive or negative offset in Hours Minutes and seconds</li>
|
||
</ul>
|
||
|
||
<h4><a class="title-link" name="example" href="#example"></a> Example</h4>
|
||
|
||
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">now_is_between</span><span class="p">(</span><span class="s">"17:30:00"</span><span class="p">,</span> <span class="s">"08:00:00"</span><span class="p">):</span>
|
||
<span class="n">do</span> <span class="n">something</span>
|
||
<span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">now_is_between</span><span class="p">(</span><span class="s">"sunset - 00:45:00"</span><span class="p">,</span> <span class="s">"sunrise + 00:45:00"</span><span class="p">):</span>
|
||
<span class="n">do</span> <span class="n">something</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h3><a class="title-link" name="friendly_name" href="#friendly_name"></a> friendly_name()</h3>
|
||
|
||
<p><code class="highlighter-rouge">frindly_name()</code> will return the Friendly Name of an entity if it has one.</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">Name</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">friendly_name</span><span class="p">(</span><span class="n">entity_id</span><span class="p">)</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h4><a class="title-link" name="returns" href="#returns"></a> Returns</h4>
|
||
|
||
<p>The friendly name of the entity if it exists or the entity id if not.</p>
|
||
|
||
<h4><a class="title-link" name="example" href="#example"></a> Example</h4>
|
||
|
||
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="n">tracker</span> <span class="o">=</span> <span class="s">"device_tracker.andrew"</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">log</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">tracker</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">friendly_name</span><span class="p">(</span><span class="n">tracker</span><span class="p">),</span> <span class="bp">self</span><span class="o">.</span><span class="n">get_tracker_state</span><span class="p">(</span><span class="n">tracker</span><span class="p">)))</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h3><a class="title-link" name="split_entity" href="#split_entity"></a> split_entity()</h3>
|
||
|
||
<p><code class="highlighter-rouge">split_entity()</code> will take a fully qualified entity id of the form <code class="highlighter-rouge">light.hall_light</code> and split it into 2 values, the device and the entity, e.g. <code class="highlighter-rouge">light</code> and <code class="highlighter-rouge">hall_light</code>.</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">device</span><span class="p">,</span> <span class="n">entity</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">split_entity</span><span class="p">(</span><span class="n">entity_id</span><span class="p">)</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h4><a class="title-link" name="parameters" href="#parameters"></a> Parameters</h4>
|
||
|
||
<h5><a class="title-link" name="entity_id" href="#entity_id"></a> entity_id</h5>
|
||
|
||
<p>Fully qualified entity id to be split.</p>
|
||
|
||
<h4><a class="title-link" name="returns" href="#returns"></a> Returns</h4>
|
||
|
||
<p>A list with 2 entries, the device and entity respectively.</p>
|
||
|
||
<h4><a class="title-link" name="example" href="#example"></a> Example</h4>
|
||
|
||
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="n">device</span><span class="p">,</span> <span class="n">entity</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">split_entity</span><span class="p">(</span><span class="n">entity_id</span><span class="p">)</span>
|
||
<span class="k">if</span> <span class="n">device</span> <span class="o">==</span> <span class="s">"scene"</span><span class="p">:</span>
|
||
<span class="n">do</span> <span class="n">something</span> <span class="n">specific</span> <span class="n">to</span> <span class="n">scenes</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h3><a class="title-link" name="get_app" href="#get_app"></a> get_app()</h3>
|
||
|
||
<p><code class="highlighter-rouge">get_app()</code> will return the instantiated object of another app running within the system. This is useful for calling functions or accessing variables that reside in different apps without requiring duplication of code.</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">get_app</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">name</span><span class="p">)</span>
|
||
</code></pre>
|
||
</div>
|
||
<h4><a class="title-link" name="parameters" href="#parameters"></a> Parameters</h4>
|
||
|
||
<h5><a class="title-link" name="name" href="#name"></a> name</h5>
|
||
|
||
<p>Name of the app required. This is the name specified in header section of the config file, not the module or class.</p>
|
||
|
||
<h4><a class="title-link" name="returns" href="#returns"></a> Returns</h4>
|
||
|
||
<p>An object reference to the class.</p>
|
||
|
||
<h4><a class="title-link" name="example" href="#example"></a> Example</h4>
|
||
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="n">MyApp</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">get_app</span><span class="p">(</span><span class="s">"MotionLights"</span><span class="p">)</span>
|
||
<span class="n">MyApp</span><span class="o">.</span><span class="n">turn_light_on</span><span class="p">()</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h3><a class="title-link" name="split_device_list" href="#split_device_list"></a> split_device_list()</h3>
|
||
|
||
<p><code class="highlighter-rouge">split_device_list()</code> will take a comma separated list of device types (or anything else for that matter) and return them as an iterable list. This is intended to assist in use cases where the App takes a list of entities from an argument, e.g. a list of sensors to monitor. If only one entry is provided, an iterable list will still be returned to avoid the need for special processing.</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">devices</span> <span class="o">=</span> <span class="n">split_device_list</span><span class="p">(</span><span class="nb">list</span><span class="p">)</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h4><a class="title-link" name="returns" href="#returns"></a> Returns</h4>
|
||
|
||
<p>A list of split devices with 1 or more entries.</p>
|
||
|
||
<h4><a class="title-link" name="example" href="#example"></a> Example</h4>
|
||
|
||
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="k">for</span> <span class="n">sensor</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">split_device_list</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">args</span><span class="p">[</span><span class="s">"sensors"</span><span class="p">]):</span>
|
||
<span class="n">do</span> <span class="n">something</span> <span class="k">for</span> <span class="n">each</span> <span class="n">sensor</span><span class="p">,</span> <span class="n">e</span><span class="o">.</span><span class="n">g</span><span class="o">.</span> <span class="n">make</span> <span class="n">a</span> <span class="n">state</span> <span class="n">subscription</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h3><a class="title-link" name="writing-to-logfiles" href="#writing-to-logfiles"></a> Writing to Logfiles</h3>
|
||
|
||
<p>AppDaemon uses 2 separate logs - the general log and the error log. An AppDaemon App can write to either of these using the supplied convenience methods <code class="highlighter-rouge">log()</code> and <code class="highlighter-rouge">error()</code>, which are provided as part of parent <code class="highlighter-rouge">AppDaemon</code> class, and the call will automatically pre-pend the name of the App making the call. The <code class="highlighter-rouge">-D</code> option of AppDaemon can be used to specify what level of logging is required and the logger objects will work as expected.</p>
|
||
|
||
<h3><a class="title-link" name="log" href="#log"></a> log()</h3>
|
||
|
||
<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">log</span><span class="p">(</span><span class="n">message</span><span class="p">,</span> <span class="n">level</span> <span class="o">=</span> <span class="s">"INFO"</span><span class="p">)</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h4><a class="title-link" name="returns" href="#returns"></a> Returns</h4>
|
||
|
||
<p>Nothing</p>
|
||
|
||
<h4><a class="title-link" name="parameters" href="#parameters"></a> Parameters</h4>
|
||
|
||
<h5><a class="title-link" name="message" href="#message"></a> Message</h5>
|
||
|
||
<p>The message to log.</p>
|
||
|
||
<h5><a class="title-link" name="level" href="#level"></a> level</h5>
|
||
|
||
<p>The log level of the message - takes a string representing the standard logger levels.</p>
|
||
|
||
<h4><a class="title-link" name="examples" href="#examples"></a> Examples</h4>
|
||
|
||
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="bp">self</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="s">"Log Test: Parameter is {}"</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">some_variable</span><span class="p">))</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">log</span><span class="p">(</span><span class="s">"Log Test: Parameter is {}"</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">some_variable</span><span class="p">),</span> <span class="n">level</span> <span class="o">=</span> <span class="s">"ERROR"</span><span class="p">)</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h3><a class="title-link" name="error" href="#error"></a> error()</h3>
|
||
|
||
<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">error</span><span class="p">(</span><span class="n">message</span><span class="p">,</span> <span class="n">level</span> <span class="o">=</span> <span class="s">"WARNING"</span><span class="p">)</span>
|
||
</code></pre>
|
||
</div>
|
||
<h4><a class="title-link" name="returns" href="#returns"></a> Returns</h4>
|
||
|
||
<p>Nothing</p>
|
||
|
||
<h4><a class="title-link" name="parameters" href="#parameters"></a> Parameters</h4>
|
||
|
||
<h5><a class="title-link" name="message" href="#message"></a> Message</h5>
|
||
|
||
<p>The message to log.</p>
|
||
|
||
<h5><a class="title-link" name="level" href="#level"></a> level</h5>
|
||
|
||
<p>The log level of the message - takes a string representing the standard logger levels.</p>
|
||
|
||
<h4><a class="title-link" name="examples" href="#examples"></a> Examples</h4>
|
||
|
||
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="bp">self</span><span class="o">.</span><span class="n">error</span><span class="p">(</span><span class="s">"Some Warning string"</span><span class="p">)</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">error</span><span class="p">(</span><span class="s">"Some Critical string"</span><span class="p">,</span> <span class="n">level</span> <span class="o">=</span> <span class="s">"CRITICAL"</span><span class="p">)</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h2><a class="title-link" name="sharing-information-between-apps" href="#sharing-information-between-apps"></a> Sharing information between Apps</h2>
|
||
|
||
<p>Sharing information between different Apps is very simple if required. Each app gets access to a global dictionary stored in a class attribute called <code class="highlighter-rouge">self.global_vars</code>. Any App can add or read any key as required. This operation is not however threadsafe so some car is needed.</p>
|
||
|
||
<p>In addition, Apps have access to the entire configuration if required, meaning they can access AppDaemon configuration items as well as parameters from other Apps. To use this, there is a class attribute called <code class="highlighter-rouge">self.config</code>. It contains a <code class="highlighter-rouge">ConfigParser</code> object, which is similar in operation to a <code class="highlighter-rouge">Dictionary</code>. To access any apps parameters, simply reference the ConfigParser object using the Apps name (form the config file) as the first key, and the parameter required as the second, for instance:</p>
|
||
|
||
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="n">other_apps_arg</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">config</span><span class="p">[</span><span class="s">"some_app"</span><span class="p">][</span><span class="s">"some_parameter"</span><span class="p">]</span><span class="o">.</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<p>To get AppDaemon’s config parameters, use the key “AppDaemon”, e.g.:</p>
|
||
|
||
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="n">app_timezone</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">config</span><span class="p">[</span><span class="s">"AppDaemon"</span><span class="p">][</span><span class="s">"time_zone"</span><span class="p">]</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<p>And finally, it is also possible to use the AppDaemon as a global area for sharing parameters across Apps. Simply add the required parameters to the AppDaemon section of your config:</p>
|
||
|
||
<div class="language-ini highlighter-rouge"><pre class="highlight"><code><span class="nn">[AppDaemon]</span>
|
||
<span class="py">ha_url</span> <span class="p">=</span> <span class="s"><some url></span>
|
||
<span class="py">ha_key</span> <span class="p">=</span> <span class="s"><some key></span>
|
||
<span class="err">...</span>
|
||
<span class="py">global_var</span> <span class="p">=</span> <span class="s">hello world</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<p>Then access it as follows:</p>
|
||
|
||
<div class="language-python highlighter-rouge"><pre class="highlight"><code><span class="n">my_global_var</span> <span class="o">=</span> <span class="n">conf</span><span class="o">.</span><span class="n">config</span><span class="p">[</span><span class="s">"AppDaemon"</span><span class="p">][</span><span class="s">"global_var"</span><span class="p">]</span>
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h2><a class="title-link" name="development-workflow" href="#development-workflow"></a> Development Workflow</h2>
|
||
|
||
<p>Developing Apps is intended to be fairly simple but is an exercise in programming like any other kind of Python programming. As such, it is expected that apps will contain syntax errors and will generate exceptions during the development process. AppDaemon makes it very easy to iterate through the development process as it will automatically reload code that has changed and also will reload code if any of the parameters in the configuration file change as well.</p>
|
||
|
||
<p>The recommended workflow for development is as follows:</p>
|
||
|
||
<ul>
|
||
<li>Open a window and tail the <code class="highlighter-rouge">appdaemon.log</code> file</li>
|
||
<li>Open a second window and tail the <code class="highlighter-rouge">error.log</code> file</li>
|
||
<li>Open a third window or the editor of your choice for editing the App</li>
|
||
</ul>
|
||
|
||
<p>With this setup, you will see that every time you write the file, AppDaemon will log the fact and let you know it has reloaded the App in the <code class="highlighter-rouge">appdaemon.log</code> file.</p>
|
||
|
||
<p>If there is an error in the compilation or a runtime error, this will be directed to the <code class="highlighter-rouge">error.log</code> file to enable you to see the error and correct it. When an error occurs, there will also be a warning message in <code class="highlighter-rouge">appdaemon.log</code> to tell you to check the error log.</p>
|
||
|
||
<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>
|
||
|
||
<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
|
||
2016-09-06 17:16:00 INFO Loading Module: /export/hass/appdaemon_test/conf/test_apps/sunset.py
|
||
...
|
||
</code></pre>
|
||
</div>
|
||
|
||
<p>Note the timestamps in the log - AppDaemon believes it is now just before sunset and will process any callbacks appropriately.</p>
|
||
|
||
<h3><a class="title-link" name="speeding-things-up" href="#speeding-things-up"></a> Speeding things up</h3>
|
||
|
||
<p>Some Apps need to run for periods of a day or two for you to test all aspects. This can be time consuming, but Time Travel can also help here in two ways. The first is by speeding up time. To do this, simply use the <code class="highlighter-rouge">-t</code> option on the command line. This specifies the amount of time a second lasts while time travelling. The default of course is 1 second, but if you change it to <code class="highlighter-rouge">0.1</code> for instance, AppDaemon will work 10x faster. If you set it to <code class="highlighter-rouge">0</code>, AppDaemon will work as fast as possible and, depending in your hardware, may be able to get through an entire day in a matter of minutes. Bear in mind however, due to the threaded nature of AppDaemon, when you are running with <code class="highlighter-rouge">-t 0</code> you may see actual events firing a little later than expected as the rest of the system tries to keep up with the timer. To set the tick time, start AppDaemon as follows:</p>
|
||
|
||
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>appdaemon -t 0.1
|
||
</code></pre>
|
||
</div>
|
||
|
||
<p>AppDaemon also has an interval flag - think of this as a second multiplier. If the flag is set to 3600 for instance, each tick of the scheduler will jump the time forward by an hour. This is good for covering vast amounts of time quickly but event firing accuracy will suffer as a result. For example:</p>
|
||
|
||
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>appdaemon -e 3600
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h3>Automatically stopping</h3>
|
||
|
||
<p>AppDaemon can be set to terminate automatically at a specific time. This can be useful if you want to repeatedly rerun a test, for example to test that random values are behaving as expected. Simply specify the end time with the <code class="highlighter-rouge">-e</code> flag as follows:</p>
|
||
|
||
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>appdaemon -e <span class="s2">"2016-06-06 10:10: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
|
||
2016-09-06 17:16:00 INFO Loading Module: /export/hass/appdaemon_test/conf/test_apps/sunset.py
|
||
...
|
||
</code></pre>
|
||
</div>
|
||
|
||
<p>The <code class="highlighter-rouge">-e</code> flag is most useful when used in conjuntion with the -s flag and optionally the <code class="highlighter-rouge">-t</code> flag. For example, to run from just before sunset, for an hour, as fast as possible:</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> -s <span class="s2">"2016-06-06 20:16:00"</span> -t 0
|
||
</code></pre>
|
||
</div>
|
||
|
||
<h3><a class="title-link" name="a-note-on-times" href="#a-note-on-times"></a> A Note on Times</h3>
|
||
|
||
<p>Some Apps you write may depend on checking times of events relative to the current time. If you are time travelling this will not work if you use standard python library calls to get the current time and date etc. For this reason, always use the AppDamon supplied <code class="highlighter-rouge">time()</code>, <code class="highlighter-rouge">date()</code> and <code class="highlighter-rouge">datetime()</code> calls, documented earlier. These calls will consult with AppDaemon’s internal time rather than the actual time and give you the correct values.</p>
|
||
|
||
|
||
</article>
|
||
|
||
|
||
</div>
|
||
|
||
|
||
<aside id="sidebar" class="grid__item one-third lap-one-whole palm-one-whole">
|
||
<div class="grid">
|
||
|
||
|
||
<section class="aside-module grid__item one-whole lap-one-half">
|
||
<div class='section'>
|
||
<h1 class="title delta">Topics</h1>
|
||
<ul class='divided sidebar-menu'>
|
||
<li>
|
||
<a href='/docs/installation/'>Installation </a>
|
||
<ul>
|
||
<li><a href='/docs/installation/python/'>Python </a></li>
|
||
<li><a href='/docs/installation/virtualenv/'>Python Virtual Env </a></li>
|
||
<li><a href='/docs/installation/docker/'>Docker </a></li>
|
||
<li><a href='/docs/installation/raspberry-pi/'>Raspberry Pi </a></li>
|
||
<li><a href='/docs/installation/raspberry-pi-all-in-one/'>Raspberrry Pi All-in-One </a></li>
|
||
<li><a href='/docs/installation/vagrant/'>Vagrant </a></li>
|
||
<li><a href='/docs/installation/synology/'>Synology </a></li>
|
||
<li><a href='/docs/installation/updating/'>Updating </a></li>
|
||
<li><a href='/docs/installation/troubleshooting/'>Troubleshooting </a></li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<a href='/docs/hassbian/'>Hassbian </a>
|
||
<ul>
|
||
<li><a href='/docs/hassbian/installation/'>Installation </a></li>
|
||
<li><a href='/docs/hassbian/customization/'>Customization </a></li>
|
||
<li><a href='/docs/hassbian/common-tasks/'>Common tasks </a></li>
|
||
<li><a href='/docs/hassbian/integrations/'>Integrations </a></li>
|
||
<li><a href='/docs/hassbian/upgrading/'>Upgrading </a></li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<a href='/docs/configuration/'>Configuration </a>
|
||
<ul>
|
||
<li><a href='/docs/configuration/yaml/'>YAML </a></li>
|
||
<li><a href='/docs/configuration/basic/'>Basic information </a></li>
|
||
<li><a href='/docs/configuration/devices/'>Setting up devices </a></li>
|
||
<li><a href='/docs/configuration/customizing-devices/'>Customizing devices and services </a></li>
|
||
<li><a href='/docs/configuration/presence-detection/'>Presence Detection </a></li>
|
||
<li><a href='/docs/configuration/troubleshooting/'>Troubleshooting </a></li>
|
||
<li><a href='/docs/configuration/securing/'>Security Check Points </a></li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
Advanced Configuration
|
||
<ul>
|
||
<li><a href='/docs/configuration/remote/'>Remote access </a></li>
|
||
<li><a href='/docs/configuration/packages/'>Packages </a></li>
|
||
<li><a href='/docs/configuration/splitting_configuration/'>Splitting up the configuration </a></li>
|
||
<li><a href='/docs/configuration/secrets/'>Storing Secrets </a></li>
|
||
<li><a href='/docs/configuration/templating/'>Templating </a></li>
|
||
<li><a href='/docs/configuration/group_visibility/'>Group Visibility </a></li>
|
||
<li><a href='/docs/configuration/events/'>Events </a></li>
|
||
<li><a href='/docs/configuration/state_object/'>State Objects </a></li>
|
||
<li><a href='/docs/configuration/platform_options/'>Entity component platform options </a></li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<a href='/docs/automation/'>Automation </a>
|
||
<ul>
|
||
<li><a href='/docs/automation/examples/'>Examples </a></li>
|
||
<li><a href='/docs/automation/trigger/'>Triggers </a></li>
|
||
<li><a href='/docs/automation/condition/'>Conditions </a></li>
|
||
<li><a href='/docs/automation/action/'>Actions </a></li>
|
||
<li><a href='/docs/automation/templating/'>Templates </a></li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<a href='/docs/frontend/'>Frontend </a>
|
||
<ul>
|
||
<li><a href='/docs/frontend/mobile/'>Android/iOS Homescreen </a></li>
|
||
<li><a href='/docs/frontend/webserver/'>Web server fingerprint </a></li>
|
||
<li><a href='/docs/frontend/browsers/'>Browser Compatibility List </a></li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<a href='/docs/backend/'>Backend </a>
|
||
<ul>
|
||
<li><a href='/docs/backend/database/'>Database </a></li>
|
||
<li><a href='/docs/backend/updater/'>Updater </a></li>
|
||
<li><a href='/developers/api/'>API </a></li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<a href='/docs/scripts/'>Scripts </a>
|
||
<ul>
|
||
<li><a href='/docs/scripts/service-calls/'>Service Calls </a></li>
|
||
<li><a href='/docs/scripts/conditions/'>Conditions </a></li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<a href='/docs/z-wave/'>Z-Wave </a>
|
||
<ul>
|
||
<li><a href='/docs/z-wave/controllers/'>Controllers </a></li>
|
||
<li><a href='/docs/z-wave/settings/'>Modifying Settings </a></li>
|
||
<li><a href='/docs/z-wave/device-specific/'>Device Specific </a></li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<a href='/docs/mqtt/'>MQTT </a>
|
||
<ul>
|
||
<li><a href='/docs/mqtt/broker/'>Broker </a></li>
|
||
<li><a href='/docs/mqtt/certificate/'>Certificate </a></li>
|
||
<li><a href='/docs/mqtt/discovery/'>Discovery </a></li>
|
||
<li><a href='/docs/mqtt/service/'>Publish service </a></li>
|
||
<li><a href='/docs/mqtt/birth_will/'>Birth and last will messages </a></li>
|
||
<li><a href='/docs/mqtt/testing/'>Testing your setup </a></li>
|
||
<li><a href='/docs/mqtt/logging/'>Logging </a></li>
|
||
<li><a href='/docs/mqtt/processing_json/'>Processing JSON </a></li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<a href='/docs/ecosystem/'>Ecosystem </a>
|
||
<ul>
|
||
<li>
|
||
<a href='/docs/ecosystem/autostart/'>Autostart </a>
|
||
<ul>
|
||
<li><a href='/docs/ecosystem/autostart/systemd/'>systemd (Linux) </a></li>
|
||
<li><a href='/docs/ecosystem/autostart/upstart/'>Upstart (Linux) </a></li>
|
||
<li><a href='/docs/ecosystem/autostart/init.d/'>init.d (Linux) </a></li>
|
||
<li><a href='/docs/ecosystem/autostart/macos/'>macOS </a></li>
|
||
<li><a href='/docs/ecosystem/autostart/synology/'>Synology NAS </a></li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<a href='/docs/ecosystem/appdaemon/'>AppDaemon </a>
|
||
<ul>
|
||
<li><a href='/docs/ecosystem/appdaemon/installation/'>Installation </a></li>
|
||
<li><a href='/docs/ecosystem/appdaemon/configuration/'>Configuration </a></li>
|
||
<li><a href='/docs/ecosystem/appdaemon/example_apps/'>Example Apps </a></li>
|
||
<li><a href='/docs/ecosystem/appdaemon/running/'>Running AppDaemon </a></li>
|
||
<li><a href='/docs/ecosystem/appdaemon/reboot/'>Starting AppDaemon at Reboot </a></li>
|
||
<li><a href='/docs/ecosystem/appdaemon/operation/'>Operation </a></li>
|
||
<li><a href='/docs/ecosystem/appdaemon/windows/'>AppDaemon on Windows </a></li>
|
||
<li><a href='/docs/ecosystem/appdaemon/updating/'>Updating AppDaemon </a></li>
|
||
<li><a href='/docs/ecosystem/appdaemon/tutorial/'>AppDaemon Tutorial </a></li>
|
||
<li><a class='active' href='/docs/ecosystem/appdaemon/api/'>AppDaemon API Reference </a></li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<a href='/docs/ecosystem/hadashboard/'>HADashboard </a>
|
||
<ul>
|
||
<li><a href='/docs/ecosystem/hadashboard/installation/'>Installation </a></li>
|
||
<li><a href='/docs/ecosystem/hadashboard/dash_config/'>Dashboard Configuration </a></li>
|
||
<li><a href='/docs/ecosystem/hadashboard/hapush/'>HAPush </a></li>
|
||
<li><a href='/docs/ecosystem/hadashboard/reboot/'>Reboot </a></li>
|
||
<li><a href='/docs/ecosystem/hadashboard/updating/'>Updating HADashboard </a></li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<a href='/docs/ecosystem/notebooks/'>Notebooks </a>
|
||
<ul>
|
||
<li><a href='/docs/ecosystem/notebooks/'>Introduction </a></li>
|
||
<li><a href='/docs/ecosystem/notebooks/installation/'>Installation </a></li>
|
||
<li><a href='/docs/ecosystem/notebooks/graph/'>Graph </a></li>
|
||
<li><a href='/docs/ecosystem/notebooks/api/'>Home Assistant API </a></li>
|
||
<li><a href='/docs/ecosystem/notebooks/database/'>Databsase </a></li>
|
||
<li><a href='/docs/ecosystem/notebooks/stats/'>Statistics </a></li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<a href='/docs/ecosystem/ios/notifications/'>iOS </a>
|
||
<ul>
|
||
<li><a href='/docs/ecosystem/ios/notifications/basic/'>Basic notifications </a></li>
|
||
<ul>
|
||
<li><a href='/docs/ecosystem/ios/notifications/examples/'>Examples </a></li>
|
||
<li><a href='/docs/ecosystem/ios/notifications/sounds/'>Sounds </a></li>
|
||
<li><a href='/docs/ecosystem/ios/notifications/architecture/'>Architecture </a></li>
|
||
<li><a href='/docs/ecosystem/ios/notifications/privacy_security_rate_limits/'>Privacy, rate limiting and security </a></li>
|
||
</ul>
|
||
<li>Advanced notifications</li>
|
||
<ul>
|
||
<li><a href='/docs/ecosystem/ios/notifications/attachments/'>Attachments </a></li>
|
||
<li><a href='/docs/ecosystem/ios/notifications/content_extensions/'>Dynamic content </a></li>
|
||
<li><a href='/docs/ecosystem/ios/notifications/actions/'>Actionable notifications </a></li>
|
||
<li><a href='/docs/ecosystem/ios/notifications/requesting_location_updates/'>Requesting location updates </a></li>
|
||
</ul>
|
||
<li><a href='/docs/ecosystem/ios/location/'>Location Tracking </a></li>
|
||
<li><a href='/docs/ecosystem/ios/integration/'>Integration with other apps </a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</ul>
|
||
</div>
|
||
</section>
|
||
|
||
</div>
|
||
</aside>
|
||
|
||
</div>
|
||
</div>
|
||
|
||
<footer>
|
||
<div class="grid-wrapper">
|
||
<div class="grid">
|
||
<div class="grid__item">
|
||
<div class="copyright">
|
||
<a rel="me" href='https://twitter.com/home_assistant'><i class="icon-twitter"></i></a>
|
||
<a rel="me" href='https://facebook.com/homeassistantio'><i class="icon-facebook"></i></a>
|
||
<a rel="me" href='https://plus.google.com/110560654828510104551'><i class="icon-google-plus"></i></a>
|
||
<a rel="me" href='https://github.com/home-assistant/home-assistant'><i class="icon-github"></i></a>
|
||
|
||
<div class="credit">
|
||
Contact us at <a href='mailto:hello@home-assistant.io'>hello@home-assistant.io</a>.<br>
|
||
Website powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>.<br />
|
||
Hosted by <a href='https://pages.github.com/'>GitHub</a> and served by <a href='https://cloudflare.com'>CloudFlare</a>.
|
||
</div>
|
||
<a rel="license" href="http://creativecommons.org/licenses/by-nc-sa/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by-nc-sa/4.0/88x31.png" /></a><br /><span xmlns:dct="http://purl.org/dc/terms/" property="dct:title">home-assistant.io</span> is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by-nc-sa/4.0/">Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License</a>.
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</footer>
|
||
|
||
<script>
|
||
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
|
||
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
|
||
g.src=('https:'==location.protocol?'//ssl':'//www')+'.google-analytics.com/ga.js';
|
||
s.parentNode.insertBefore(g,s)}(document,'script'));
|
||
</script>
|
||
</body>
|
||
</html> |