home-assistant.github.io/docs/ecosystem/scenegen/index.html
2017-04-29 10:26:16 +00:00

436 lines
25 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!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>SceneGen - Home Assistant</title>
<meta name="author" content="Home Assistant">
<meta name="description" content="Scenegen is a scene generation tool for Home Assistant">
<meta name="viewport" content="width=device-width">
<link rel="canonical" href="https://home-assistant.io/docs/ecosystem/scenegen/">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="SceneGen">
<meta property="og:site_name" content="Home Assistant">
<meta property="og:url" content="https://home-assistant.io/docs/ecosystem/scenegen/">
<meta property="og:type" content="article">
<meta property="og:description" content="Scenegen is a scene generation tool for Home Assistant">
<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="SceneGen">
<meta name="twitter:description" content="Scenegen is a scene generation tool for Home Assistant">
<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/scenegen.markdown'>Edit this page on GitHub</a></div>
<header>
<h1 class="title indent">
SceneGen
</h1>
</header>
<hr class="divider">
<p>Scenegen is a scene generation tool for <a href="https://home-assistant.io/">Home Assistant</a> home automation software. It creates scenes by example, by reading the current states of devices and outputting a corresponding scene. Scenegen is written in python using Home Assistants RESTFul API so can be run from anywhere. It currently supports lights and switches only.</p>
<h2><a class="title-link" name="installation" href="#installation"></a> Installation</h2>
<h3><a class="title-link" name="clone-the-repository" href="#clone-the-repository"></a> Clone the Repository</h3>
<p>Clone the <a href="https://github.com/home-assistant/scenegen"><strong>scenegen</strong></a> repository to the current local directory on your machine.</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>git clone https://github.com/home-assistant/scenegen.git
</code></pre>
</div>
<p>Change your working directory to the repository root. Moving forward, we will be working from this directory.</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span><span class="nb">cd </span>scenegen
</code></pre>
</div>
<h2><a class="title-link" name="install-prerequisites" href="#install-prerequisites"></a> Install Prerequisites</h2>
<p>Before running <code class="highlighter-rouge">SceneGen</code> you will need to add some python prerequisites:</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>sudo pip3 install configparser
</code></pre>
</div>
<p>You should now be ready to run <code class="highlighter-rouge">scenegen</code></p>
<h2><a class="title-link" name="basic-operation" href="#basic-operation"></a> Basic Operation</h2>
<div class="highlighter-rouge"><pre class="highlight"><code>usage: scenegen [-h] [-k KEY] [-s SCENENAME] [-m MAPFILE] [-f FILTER]
[-c {xy_color,rgb_color,color_temp,color_name}] [-t TYPES]
url
positional arguments:
url url for Home Assistant instance
optional arguments:
-h, --help show this help message and exit
-k KEY, --key KEY API Key of Home Assistant instance
-s SCENENAME, --scenename SCENENAME
Name of scene to generate
-m MAPFILE, --mapfile MAPFILE
Name of mapfile to enable device filtering
-f FILTER, --filter FILTER
Comma separated list of device collections as defined
in mapfile
-c {xy_color,rgb_color,color_temp,color_name}, --colortype {xy_color,rgb_color,color_temp,color_name}
color type to use
-t TYPES, --types TYPES
list of device types to include
</code></pre>
</div>
<p>For basic operation just supply the url and optionally the api key (using the key option) on the command line and scenegen will output a list of all lights and switches with their attributes. Optionally use the <code class="highlighter-rouge">--scenename</code> flag to explicitly set the scenename.</p>
<div class="highlighter-rouge"><pre class="highlight"><code>$ ./scenegen.py https://&lt;some url&gt; -k &lt;some api key&gt;
name: My New Scene
entities:
light.bedroom:
state: on
brightness: 28
light.kitchen:
state: off
light.living_room:
state: off
light.bedside:
state: on
brightness: 125
color_temp: 412
light.office_level_29:
state: on
brightness: 28
</code></pre>
</div>
<p>This output can be cut and pasted into your configuration.yaml file as required (ensuring correct indentatation of course).</p>
<p>Scenegen supports all documented effects for lights including transitions and flash effects, however generally it is easier to run scenegen to get the basic setup and add any effects manually later.</p>
<p>Note that depending on the type of light there may be a delay in actually setting up its parameters and Home Assistant actually recieving that state. For instance, if you set a scene up with the Hue App, Home Assistant wont see those changes for up to 10 seconds. Turning on a ZWave light might not be seen for an entire poll interval. For this reason, its good practice to wait for a while after the scene is setup before running scenegen. Alternatively, perform all setup using the Home Assistant frontend and it will instantly have the required state for capture.</p>
<h2><a class="title-link" name="advanced-usage" href="#advanced-usage"></a> Advanced Usage</h2>
<p>For a more advanced way to use the output try the following. In configuration.yaml add the following line:</p>
<div class="highlighter-rouge"><pre class="highlight"><code>scene: !include_dir_list scenes
</code></pre>
</div>
<p>This will tell home assistant to look in the subdirectory <code class="highlighter-rouge">scenes</code> for yaml files containing scene information. Each file will be named for the scene it will create and should contain information formatted as above. Then simply run Scenegen and redirect its output to the scenes subdirectory:</p>
<div class="highlighter-rouge"><pre class="highlight"><code>$ ./scenegen.py https://&lt;some url&gt; -k &lt;some api key&gt; &gt; scenes/my_new_scene.yaml
</code></pre>
</div>
<p>This will create a new scene called <code class="highlighter-rouge">my_new_scene</code> which will automatically be picked up by Home Assistant on the next restart.</p>
<h2><a class="title-link" name="colors" href="#colors"></a> Colors</h2>
<p>Scenegen allows colors to be captured, and in fact Home Assistant light entities store up to 4 different ways of specifying the colors. This is redundant for creating scenes so Scenegen picks 1 and goes with it. The default is <code class="highlighter-rouge">color_temp</code> but you can change this with the <code class="highlighter-rouge">--colortype</code> flag, supported options are <code class="highlighter-rouge">xy_color</code>, <code class="highlighter-rouge">rgb_color</code>, <code class="highlighter-rouge">color_temp</code> and <code class="highlighter-rouge">color_name</code>.</p>
<h2><a class="title-link" name="types" href="#types"></a> Types</h2>
<p>By default, Scenegen will list all lights and switches. To restrict the device type use the <code class="highlighter-rouge">--types</code> option and supply a comma separated list (no spaces) of types to output. e.g.:</p>
<div class="highlighter-rouge"><pre class="highlight"><code>./scenegen.py https://&lt;some url&gt; -k &lt;some api key&gt; --types light,switch
</code></pre>
</div>
<p>or:</p>
<div class="highlighter-rouge"><pre class="highlight"><code>./scenegen.py https://&lt;some url&gt; -k &lt;some api key&gt; --types light
</code></pre>
</div>
<p>This will make more sense as and when more types are added.</p>
<h2><a class="title-link" name="maps-and-filters" href="#maps-and-filters"></a> Maps and Filters</h2>
<p>Maps allow you to specify and label various subsets of devices that you want to work on together. A mapfile is specified using the <code class="highlighter-rouge">--mapfile</code> option and is a <code class="highlighter-rouge">.ini</code> style file consisting of section headers and entries. The section headers specify a region or zone or otherwise organized selection of entities you want to filter on, and it is mandatory to have at least one. If you create a map file like this:</p>
<div class="highlighter-rouge"><pre class="highlight"><code>[entities]
light.living_room:
light.dining_room:
</code></pre>
</div>
<p>The trailing colons are necessary to prevent parsing errors for including just keys, as opposed to key=value so just go with it - it reminds us of YAML ;)</p>
<p>If you run scenegen with the <code class="highlighter-rouge">--mapfile</code> argument pointing to that file you will only get output for the listed entities (the name of the section is irrelevant if not using the <code class="highlighter-rouge">--filter</code> option). A more complex mapfile might look like this:</p>
<div class="highlighter-rouge"><pre class="highlight"><code>[Outside]
light.porch:
switch.path_lights:
[Living Room]
light.living_room_front:
light.living_room_back:
[Bedroom]
light.bedside:
</code></pre>
</div>
<p>Again, if you run with that map file it will output all of the entities listed, however you now have the possibility of restricting output devices based on the sections they are in, using the <code class="highlighter-rouge">--filter</code> option and supplying a comma separated list of sections you want to include, for instance:</p>
<div class="highlighter-rouge"><pre class="highlight"><code>./scenegen.py https://&lt;some url&gt; -k &lt;some api key&gt; --mapfile map.cfg --filter "Outside,Living Room"
</code></pre>
</div>
<p>The intended use of the mapfile and filter is that you create a map of all your devices and organize them into zones that you are interested in creating scenes for and use the filter to limit output to that zone. For instance you might want to create 3 or 4 scenes for your living room, and once the map is set up you can easily do so without the addition of unwanted devices.</p>
<h2><a class="title-link" name="updating-scenegen" href="#updating-scenegen"></a> Updating SceneGen</h2>
<p>To update SceneGen after a new version is released, just run the following command to update your copy:</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>git pull
</code></pre>
</div>
</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/virtualenv/'>Python Virtual Env </a></li>
<li><a href='/docs/installation/raspberry-pi-all-in-one/'>Raspberry Pi All-in-One </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/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/platform_options/'>Entity component platform options </a></li>
</ul>
</li>
<li>
Core objects
<ul>
<li><a href='/docs/configuration/events/'>Events </a></li>
<li><a href='/docs/configuration/state_object/'>State Objects </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/tools/'>Tools and Helpers </a>
<ul>
<li><a href='/docs/tools/dev-tools/'>Developer Tools </a></li>
<li><a href='/docs/tools/hass/'>hass </a></li>
<li><a href='/docs/tools/scripts/'>Scripts </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/ios/'>iOS </a>
<ul>
<li><a href='/docs/ecosystem/ios/notifications/basic/'>Basic notifications </a></li>
<ul>
<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>
<li>
<a href='/docs/ecosystem/'>Ecosystem </a>
<ul>
<li>
<a href='/docs/autostart/'>Autostart </a>
<ul>
<li><a href='/docs/autostart/systemd/'>systemd (Linux) </a></li>
<li><a href='/docs/autostart/upstart/'>Upstart (Linux) </a></li>
<li><a href='/docs/autostart/init.d/'>init.d (Linux) </a></li>
<li><a href='/docs/autostart/macos/'>macOS </a></li>
<li><a href='/docs/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 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>
Remote access
<ul>
<li><a href='/docs/ecosystem/apache/'>Apache </a></li>
<li><a href='/docs/ecosystem/nginx/'>NGINX </a></li>
<li><a href='/docs/ecosystem/tor/'>Tor Onion Service </a></li>
</ul>
</li>
<li>
Certificates
<ul>
<li><a href='/docs/ecosystem/certificates/tls_self_signed_certificate/'>Self-signed certificate </a></li>
<li><a href='/docs/ecosystem/certificates/tls_domain_certificate/'>Certificate domain owners </a></li>
<li><a href='/docs/ecosystem/certificates/lets_encrypt/'>Let's Encrypt (detailed) </a></li>
</ul>
</li>
<li>
Backup
<ul>
<li><a href='/docs/ecosystem/backup/backup_github/'>Backup to GitHub </a></li>
<li><a href='/docs/ecosystem/backup/backup_dropbox/'>Backup to Dropbox </a></li>
<li><a href='/docs/ecosystem/backup/backup_usb/'>Backup to USB device </a></li>
</ul>
</li>
<li><a class='active' href='/docs/ecosystem/scenegen/'>scenegen </a></li>
<li><a href='/docs/ecosystem/synology/'>Synology </a></li>
<li><a href='/docs/ecosystem/hass-configurator/'>HASS Configurator </a></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>