316 lines
No EOL
18 KiB
HTML
316 lines
No EOL
18 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>Python API - Home Assistant</title>
|
||
<meta name="author" content="Paulus Schoutsen">
|
||
<meta name="description" content="Home Assistant Python API documentation">
|
||
|
||
<meta name="viewport" content="width=device-width">
|
||
<link rel="canonical" href="https://home-assistant.io/developers/python_api/">
|
||
|
||
<meta property="fb:app_id" content="338291289691179">
|
||
<meta property="og:title" content="Python API">
|
||
<meta property="og:site_name" content="Home Assistant">
|
||
<meta property="og:url" content="https://home-assistant.io/developers/python_api/">
|
||
<meta property="og:type" content="website">
|
||
<meta property="og:description" content="Home Assistant Python API documentation">
|
||
<meta property="og:image" content="https://home-assistant.io/images/home-assistant-logo-2164x2164.png">
|
||
|
||
<meta name="twitter:card" content="summary">
|
||
<meta name="twitter:site" content="@home_assistant">
|
||
|
||
<meta name="twitter:title" content="Python API">
|
||
<meta name="twitter:description" content="Home Assistant Python API documentation">
|
||
<meta name="twitter:image" content="https://home-assistant.io/images/home-assistant-logo-2164x2164.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='/images/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>
|
||
<ul>
|
||
<li><a href='/getting-started/'>Installing Home Assistant</a></li>
|
||
<li><a href='/getting-started/configuration/'>Configuration basics</a></li>
|
||
<li><a href='/getting-started/devices/'>Adding devices</a></li>
|
||
<li><a href='/getting-started/presence-detection/'>Presence detection</a></li>
|
||
<li><a href='/getting-started/automation/'>Automation</a></li>
|
||
<li><a href='/getting-started/templating/'>Templating</a></li>
|
||
<li><a href='/cookbook'>Configuration cookbook</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href='/components/'>Components</a></li>
|
||
<li>
|
||
<a href="/developers/">Developers</a>
|
||
<ul>
|
||
<li><a href="/developers/architecture/">Architecture</a></li>
|
||
<li><a href="/developers/frontend/">Frontend development</a></li>
|
||
<li><a href="/developers/creating_components/">
|
||
Creating components
|
||
</a></li>
|
||
<li><a href="/developers/add_new_platform/">
|
||
Adding platform support
|
||
</a></li>
|
||
<li><a href="/developers/api/">API</a></li>
|
||
<li><a href="/developers/credits/">Credits</a></li>
|
||
</ul>
|
||
</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">
|
||
|
||
|
||
<header>
|
||
<h1 class="title indent">
|
||
Python API
|
||
</h1>
|
||
</header>
|
||
<hr class="divider">
|
||
|
||
|
||
<p>In the package <a href="https://github.com/balloob/home-assistant/blob/master/homeassistant/remote.py"><code>homeassistant.remote</code></a> a Python API on top of the <a href="/developers/api/">HTTP API</a> can be found.</p>
|
||
|
||
<p>This page is not a full documentation it’s more a collection of some example. A simple way to get all current entities is to visit the “Set State” page in the “Developer Tools”. For the examples below just choose one from the available entries. Here the sensor <code>sensor.office_temperature</code> and the switch <code>switch.livingroom_pin_2</code> are used.</p>
|
||
|
||
<p>First import the module and setup the basics.</p>
|
||
|
||
<div class="highlighter-coderay"><div class="CodeRay">
|
||
<div class="code"><pre><span class="keyword">import</span> <span class="include">homeassistant.remote</span> <span class="keyword">as</span> remote
|
||
|
||
api = remote.API(<span class="string"><span class="delimiter">'</span><span class="content">host</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">password</span><span class="delimiter">'</span></span>)
|
||
print(remote.validate_api(api))
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
|
||
<p>This snippets shows how to use the <code>homeassistant.remote</code> package in another way.</p>
|
||
|
||
<div class="highlighter-coderay"><div class="CodeRay">
|
||
<div class="code"><pre><span class="keyword">import</span> <span class="include">homeassistant.remote</span> <span class="keyword">as</span> remote
|
||
|
||
api = remote.API(<span class="string"><span class="delimiter">'</span><span class="content">host</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">password</span><span class="delimiter">'</span></span>)
|
||
hass = remote.HomeAssistant(api)
|
||
hass.start()
|
||
living_room = hass.states.get(<span class="string"><span class="delimiter">'</span><span class="content">group.living_room</span><span class="delimiter">'</span></span>)
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
|
||
<h3><a class="title-link" name="get-details-about-servies-and-events" href="#get-details-about-servies-and-events"></a> Get details about servies and events</h3>
|
||
|
||
<p>Similar to the output in the “Developer Tools” of the frontend.</p>
|
||
|
||
<div class="highlighter-coderay"><div class="CodeRay">
|
||
<div class="code"><pre><span class="keyword">import</span> <span class="include">homeassistant.remote</span> <span class="keyword">as</span> remote
|
||
|
||
api = remote.API(<span class="string"><span class="delimiter">'</span><span class="content">host</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">password</span><span class="delimiter">'</span></span>)
|
||
|
||
print(<span class="string"><span class="delimiter">'</span><span class="content">-- Available services:</span><span class="delimiter">'</span></span>)
|
||
services = remote.get_services(api)
|
||
<span class="keyword">for</span> service <span class="keyword">in</span> services:
|
||
print(service[<span class="string"><span class="delimiter">'</span><span class="content">services</span><span class="delimiter">'</span></span>])
|
||
|
||
print(<span class="string"><span class="delimiter">'</span><span class="char">\n</span><span class="content">-- Available event</span><span class="delimiter">'</span></span>)
|
||
events = remote.get_event_listeners(api)
|
||
<span class="keyword">for</span> event <span class="keyword">in</span> events:
|
||
print(event)
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
|
||
<h3><a class="title-link" name="get-the-state-of-an-entity" href="#get-the-state-of-an-entity"></a> Get the state of an entity</h3>
|
||
|
||
<p>To get the details of a single entity the <code>get_state</code> method is used.</p>
|
||
|
||
<div class="highlighter-coderay"><div class="CodeRay">
|
||
<div class="code"><pre><span class="keyword">import</span> <span class="include">homeassistant.remote</span> <span class="keyword">as</span> remote
|
||
|
||
api = remote.API(<span class="string"><span class="delimiter">'</span><span class="content">host</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">password</span><span class="delimiter">'</span></span>)
|
||
office_temperature = remote.get_state(api, <span class="string"><span class="delimiter">'</span><span class="content">sensor.office_temperature</span><span class="delimiter">'</span></span>)
|
||
print(<span class="string"><span class="delimiter">'</span><span class="content">{} is {} {}.</span><span class="delimiter">'</span></span>.format(office_temperature.attributes[<span class="string"><span class="delimiter">'</span><span class="content">friendly_name</span><span class="delimiter">'</span></span>],
|
||
office_temperature.state,
|
||
office_temperature.attributes[<span class="string"><span class="delimiter">'</span><span class="content">unit_of_measurement</span><span class="delimiter">'</span></span>]
|
||
)
|
||
)
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
|
||
<p>The output is composed out of the details which are stored for this entity.</p>
|
||
|
||
<div class="highlighter-coderay"><div class="CodeRay">
|
||
<div class="code"><pre>Office Temperature is 19 °C.
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
|
||
<p>The exact same thing is working for a switch. The difference is that both entities have different attributes.</p>
|
||
|
||
<div class="highlighter-coderay"><div class="CodeRay">
|
||
<div class="code"><pre><span class="keyword">import</span> <span class="include">homeassistant.remote</span> <span class="keyword">as</span> remote
|
||
|
||
api = remote.API(<span class="string"><span class="delimiter">'</span><span class="content">host</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">password</span><span class="delimiter">'</span></span>)
|
||
switch_livingroom = remote.get_state(api, <span class="string"><span class="delimiter">'</span><span class="content">switch.livingroom_pin_2</span><span class="delimiter">'</span></span>)
|
||
print(<span class="string"><span class="delimiter">'</span><span class="content">{} is {}.</span><span class="delimiter">'</span></span>.format(switch_livingroom.attributes[<span class="string"><span class="delimiter">'</span><span class="content">friendly_name</span><span class="delimiter">'</span></span>],
|
||
switch_livingroom.state
|
||
)
|
||
)
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
|
||
<h3><a class="title-link" name="set-the-state-of-an-entity" href="#set-the-state-of-an-entity"></a> Set the state of an entity</h3>
|
||
|
||
<p>Of course, it’s possible to set the state.</p>
|
||
|
||
<div class="highlighter-coderay"><div class="CodeRay">
|
||
<div class="code"><pre><span class="keyword">import</span> <span class="include">homeassistant.remote</span> <span class="keyword">as</span> remote
|
||
<span class="keyword">from</span> <span class="include">homeassistant.const</span> <span class="keyword">import</span> <span class="include">STATE_ON</span>
|
||
|
||
api = remote.API(<span class="string"><span class="delimiter">'</span><span class="content">host</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">password</span><span class="delimiter">'</span></span>)
|
||
remote.set_state(api, <span class="string"><span class="delimiter">'</span><span class="content">sensor.office_temperature</span><span class="delimiter">'</span></span>, new_state=<span class="integer">123</span>)
|
||
remote.set_state(api, <span class="string"><span class="delimiter">'</span><span class="content">switch.livingroom_pin_2</span><span class="delimiter">'</span></span>, new_state=STATE_ON)
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
|
||
<p>The state will be set to those value until the next update occurs.</p>
|
||
|
||
<h3><a class="title-link" name="blinking-all-entites-of-a-domain" href="#blinking-all-entites-of-a-domain"></a> Blinking all entites of a domain</h3>
|
||
|
||
<p>If you want to turn on all entities of a domain, just a service which was retrieved by <code>get_services</code>.</p>
|
||
|
||
<div class="highlighter-coderay"><div class="CodeRay">
|
||
<div class="code"><pre><span class="keyword">import</span> <span class="include">time</span>
|
||
<span class="keyword">import</span> <span class="include">homeassistant.remote</span> <span class="keyword">as</span> remote
|
||
|
||
api = remote.API(<span class="string"><span class="delimiter">'</span><span class="content">host</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">password</span><span class="delimiter">'</span></span>)
|
||
domain = <span class="string"><span class="delimiter">'</span><span class="content">switch</span><span class="delimiter">'</span></span>
|
||
|
||
remote.call_service(api, domain, <span class="string"><span class="delimiter">'</span><span class="content">turn_on</span><span class="delimiter">'</span></span>)
|
||
time.sleep(<span class="integer">10</span>)
|
||
remote.call_service(api, domain, <span class="string"><span class="delimiter">'</span><span class="content">turn_off</span><span class="delimiter">'</span></span>)
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
|
||
<h3><a class="title-link" name="control-a-single-entity" href="#control-a-single-entity"></a> Control a single entity</h3>
|
||
|
||
<p>To turn on or off a single switch. The ID of the entity is needed as attribute.</p>
|
||
|
||
<div class="highlighter-coderay"><div class="CodeRay">
|
||
<div class="code"><pre><span class="keyword">import</span> <span class="include">time</span>
|
||
<span class="keyword">import</span> <span class="include">homeassistant.remote</span> <span class="keyword">as</span> remote
|
||
|
||
api = remote.API(<span class="string"><span class="delimiter">'</span><span class="content">host</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">password</span><span class="delimiter">'</span></span>)
|
||
domain = <span class="string"><span class="delimiter">'</span><span class="content">switch</span><span class="delimiter">'</span></span>
|
||
switch_name = <span class="string"><span class="delimiter">'</span><span class="content">switch.livingroom_pin_2</span><span class="delimiter">'</span></span>
|
||
|
||
remote.call_service(api, domain, <span class="string"><span class="delimiter">'</span><span class="content">turn_on</span><span class="delimiter">'</span></span>, {<span class="string"><span class="delimiter">'</span><span class="content">entity_id</span><span class="delimiter">'</span></span>: <span class="string"><span class="delimiter">'</span><span class="content">{}</span><span class="delimiter">'</span></span>.format(switch_name)})
|
||
time.sleep(<span class="integer">5</span>)
|
||
remote.call_service(api, domain, <span class="string"><span class="delimiter">'</span><span class="content">turn_off</span><span class="delimiter">'</span></span>, {<span class="string"><span class="delimiter">'</span><span class="content">entity_id</span><span class="delimiter">'</span></span>: <span class="string"><span class="delimiter">'</span><span class="content">{}</span><span class="delimiter">'</span></span>.format(switch_name)})
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
|
||
<h3><a class="title-link" name="send-a-notification" href="#send-a-notification"></a> Send a notification</h3>
|
||
|
||
<p>The example uses the jabber notification platform to send a single message to the given recipient in the <code>configuration.yaml</code> file.</p>
|
||
|
||
<div class="highlighter-coderay"><div class="CodeRay">
|
||
<div class="code"><pre><span class="keyword">import</span> <span class="include">homeassistant.remote</span> <span class="keyword">as</span> remote
|
||
|
||
api = remote.API(<span class="string"><span class="delimiter">'</span><span class="content">host</span><span class="delimiter">'</span></span>, <span class="string"><span class="delimiter">'</span><span class="content">password</span><span class="delimiter">'</span></span>)
|
||
domain = <span class="string"><span class="delimiter">'</span><span class="content">notify</span><span class="delimiter">'</span></span>
|
||
data = {<span class="string"><span class="delimiter">"</span><span class="content">title</span><span class="delimiter">"</span></span>:<span class="string"><span class="delimiter">"</span><span class="content">Test</span><span class="delimiter">"</span></span>, <span class="string"><span class="delimiter">"</span><span class="content">message</span><span class="delimiter">"</span></span>:<span class="string"><span class="delimiter">"</span><span class="content">A simple test message from HA.</span><span class="delimiter">"</span></span>}
|
||
|
||
remote.call_service(api, domain, <span class="string"><span class="delimiter">'</span><span class="content">jabber</span><span class="delimiter">'</span></span>, data)
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
|
||
<p>For more details please check the source of <a href="https://github.com/balloob/home-assistant/blob/master/homeassistant/remote.py">homeassistant.remote</a>.</p>
|
||
|
||
|
||
</article>
|
||
|
||
|
||
</div>
|
||
|
||
|
||
</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://github.com/balloob/home-assistant'><i class="icon-github"></i></a>
|
||
|
||
<div class="credit">
|
||
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>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</footer>
|
||
|
||
<!--[if lt IE 7]>
|
||
<p class="chromeframe">You are using an <strong>outdated</strong> browser. Please <a href="http://browsehappy.com/">upgrade your browser</a> or <a href="http://www.google.com/chromeframe/?redirect=true">activate Google Chrome Frame</a> to improve your experience.</p>
|
||
<![endif]-->
|
||
|
||
<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> |