home-assistant.github.io/components/apple_tv/index.html
2017-11-05 14:24:39 +00:00

492 lines
24 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>Apple TV - Home Assistant</title>
<meta name="author" content="Home Assistant">
<meta name="description" content="Instructions how to integrate Apple TV devices into Home Assistant.">
<meta name="viewport" content="width=device-width">
<link rel="canonical" href="https://home-assistant.io/components/apple_tv/">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="Apple TV">
<meta property="og:site_name" content="Home Assistant">
<meta property="og:url" content="https://home-assistant.io/components/apple_tv/">
<meta property="og:type" content="article">
<meta property="og:description" content="Instructions how to integrate Apple TV devices into 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="Apple TV">
<meta name="twitter:description" content="Instructions how to integrate Apple TV devices into Home Assistant.">
<meta name="twitter:image" content="https://home-assistant.io/images/default-social.png">
<link href="/stylesheets/screen.css" media="screen, projection, print" 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 class='site-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>
<li><a href='#' class='show-search'><i class="icon-search"></i></a></li>
</ul>
</nav>
<div class='search-container' style='display: none'>
<div class='search'>
<i class="icon-search"></i>
<input id='search' placeholder='Search the docs…'>
<a href='#' class='close'><i class="icon-remove-sign"></i></a>
</div>
</div>
</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">
Apple TV
</h1>
</header>
<hr class="divider">
<p>The <code class="highlighter-rouge">apple_tv</code> platform allows you to control an Apple TV (3rd and 4th generation). See the <a href="/components/remote.apple_tv/">remote platform</a> if you want to send remote control buttons, e.g. arrow keys.</p>
<p class="note">
Currently, you must have Home Sharing enabled for this to work. Support for pairing Home Assistant with your device will be supported in a later release.
</p>
<p>To use this component, you must first install some system libraries and a compiler. For Debian or a similar system, this should be enough:</p>
<div class="language-shell highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>sudo apt-get install build-essential libssl-dev libffi-dev python-dev
</code></pre>
</div>
<p>If you want to discover new devices automatically, just make sure you have <code class="highlighter-rouge">discovery:</code> in your <code class="highlighter-rouge">configuration.yaml</code> file. To manually add one or more Apple TVs to your installation, add the following to your <code class="highlighter-rouge">configuration.yaml</code> file:</p>
<div class="language-yaml highlighter-rouge"><pre class="highlight"><code><span class="c1"># Example configuration.yaml entry</span>
<span class="s">apple_tv</span><span class="pi">:</span>
<span class="pi">-</span> <span class="s">host</span><span class="pi">:</span> <span class="s">IP_1</span>
<span class="s">login_id</span><span class="pi">:</span> <span class="s">LOGIN_ID_1</span>
<span class="s">name</span><span class="pi">:</span> <span class="s">NAME_1</span>
<span class="s">start_off</span><span class="pi">:</span> <span class="s">START_OFF_1</span>
<span class="s">credentials</span><span class="pi">:</span> <span class="s">CREDENTIALS_1</span>
<span class="pi">-</span> <span class="s">host</span><span class="pi">:</span> <span class="s">IP_2</span>
<span class="s">login_id</span><span class="pi">:</span> <span class="s">LOGIN_ID_2</span>
<span class="s">name</span><span class="pi">:</span> <span class="s">NAME_2</span>
<span class="s">start_off</span><span class="pi">:</span> <span class="s">START_OFF_2</span>
<span class="s">credentials</span><span class="pi">:</span> <span class="s">CREDENTIALS_2</span>
</code></pre>
</div>
<p>Configuration variables:</p>
<ul>
<li><strong>host</strong> (<em>Required</em>): The IP-address of the device.</li>
<li><strong>login_id</strong> (<em>Required</em>): An identifier used to login to the device, see below.</li>
<li><strong>name</strong> (<em>Optional</em>): The name of the device used in the frontend.</li>
<li><strong>start_off</strong> (<em>Optional</em>): Set to true if the device should start in fake standby.</li>
<li><strong>credentials</strong> (<em>Optional</em>): Credentials used for AirPlay playback.</li>
</ul>
<p>In order to connect to the device, you need a <em>login id</em>. The easiest way to obtain this identifier is to use the <code class="highlighter-rouge">apple_tv_scan</code> service (described below). Additional information about <code class="highlighter-rouge">start_off</code> and <code class="highlighter-rouge">credentials</code> can also be found under the guides section.</p>
<h2><a class="title-link" name="guides" href="#guides"></a> Guides</h2>
<h3><a class="title-link" name="scanning-for-devices" href="#scanning-for-devices"></a> Scanning for devices</h3>
<p>To scan for devices, press the icon in the upper left corner and select the leftmost icon according to the image:</p>
<p><img src="/images/screenshots/developer-tools.png" /></p>
<p>Select <code class="highlighter-rouge">apple_tv</code> as domain and <code class="highlighter-rouge">apple_tv_scan</code> as service then press the button:</p>
<p><img src="/images/components/apple_tv/scan_start.jpg" /></p>
<p>Scanning will be done for three seconds and notification will be shown in the state view with all found devices:</p>
<p><img src="/images/components/apple_tv/scan_result.jpg" /></p>
<p>Alternatively, you may use the application <code class="highlighter-rouge">atvremote</code>. Install it with <code class="highlighter-rouge">pip3 install --upgrade pyatv</code> in your Home Assistant environment (note: do <em>not</em> use sudo). Then run <code class="highlighter-rouge">atvremote scan</code> to scan for all devices (try again if a device is missing):</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>atvremote scan
Found Apple TVs:
- Apple TV at 10.0.10.22 <span class="o">(</span>login id: 00000000-1234-5678-9012-345678901234<span class="o">)</span>
Note: You must use <span class="s1">'pair'</span> with devices that have home sharing disabled
</code></pre>
</div>
<p>Just copy and paste the login id from the device you want to add. For more details about <code class="highlighter-rouge">atvremote</code>, see: <a href="http://pyatv.readthedocs.io/en/master/atvremote.html">this page</a>.</p>
<h3><a class="title-link" name="my-apple-tv-turns-on-when-i-restart-home-assistant" href="#my-apple-tv-turns-on-when-i-restart-home-assistant"></a> My Apple TV turns on when I restart Home Assistant</h3>
<p>The Apple TV will automatically turn on if a request is sent to it, e.g., if a button is pressed, something is streamed to it via AirPlay or if current state (currently playing) is accessed. This is how Apple has designed it, and it will cause problems if you are using HDMI CEC. Every time Home Assistant is started, a new request is sent to the device to figure out what is currently playing. When using CEC, this will wake up your TV and other devices you have configured.</p>
<p>So, if your TV is randomly turning on, this is probably the reason. As stated, this is by design, and there is no real fix for it. Theres also no known way to turn off the Apple TV via the protocol used for communication. You have the following options:</p>
<ul>
<li>Do not use this platform</li>
<li>Disable HDMI CEC on your Apple TV</li>
<li>Use “fake standby”</li>
</ul>
<p>The first two points are quite obvious. Fake standby is a concept implemented in this platform that disables all requests to the device and makes it appear as being “off” in the web interface. This will make sure that the device is not woken up, but it will of course not show any information or allow you to control it. It is however easy to turn it on (or off) in the web interface or to use an automation with <code class="highlighter-rouge">turn_on</code>. To make it more useful, you can write automations that turn it on or off depending on some other device, like the input source on your receiver.</p>
<p>To put a device into fake standby when starting Home Assistant, add <code class="highlighter-rouge">start_off: true</code> to your configuration.</p>
<p class="note warning">
Turning the device on/off in the user interface will <em>not</em> turn the physical device on/off according to the description above.
</p>
<h3><a class="title-link" name="setting-up-device-authentication" href="#setting-up-device-authentication"></a> Setting up device authentication</h3>
<p>If you, when playing media with <code class="highlighter-rouge">play_url</code>, get the following error message:</p>
<p><em>“This AirPlay connection requires iOS 7.1 or later, OS X 10.10 or later, or iTunes 11.2 or later.”</em></p>
<p>then device authentication is required. Press the icon in the upper left corner and select the leftmost icon according to the image below:</p>
<p><img src="/images/screenshots/developer-tools.png" /></p>
<p>Select <code class="highlighter-rouge">apple_tv</code> as domain, <code class="highlighter-rouge">apple_tv_authenticate</code> as service and enter <code class="highlighter-rouge"><span class="p">{</span><span class="nt">"entity_id"</span><span class="p">:</span><span class="w"> </span><span class="s2">"XXX"</span><span class="p">}</span></code> into “Service Data”, but replace XXX with the entity id of your device (e.g. <code class="highlighter-rouge">media_player.apple_tv</code>). Press the button and hopefully you are presented with an input dialog asking for a pin code:</p>
<p><img src="/images/components/apple_tv/auth_start.jpg" /></p>
<p>If no dialog appears, go back to the states view and display it from there (press <code class="highlighter-rouge">CONFIGURE</code> as displayed in the image):</p>
<p><img src="/images/components/apple_tv/auth_pin.jpg" /></p>
<p>A PIN code should now be visible on your TV, just enter it into the dialog and press “Confirm”. You should see if it succeeded in the state view. Copy the credentials and insert it into your configuration (make sure you copy everything, it should be 81 characters) after <code class="highlighter-rouge">credentials:</code> with no line-break:</p>
<div class="language-yaml highlighter-rouge"><pre class="highlight"><code><span class="c1"># Example configuration.yaml entry</span>
<span class="s">apple_tv</span><span class="pi">:</span>
<span class="pi">-</span> <span class="s">host</span><span class="pi">:</span> <span class="s">10.0.0.20</span>
<span class="s">login_id</span><span class="pi">:</span> <span class="s">00000000-1234-5678-9012-345678901234</span>
<span class="s">credentials</span><span class="pi">:</span> <span class="s">1B8C387DDB59BDF6:CF5ABB6A2C070688F5926ADB7C010F6DF847252C15F9BDB6DA3E09D6591E90E5</span>
</code></pre>
</div>
<p>Restart Home Assistant, and you should now be able to use <code class="highlighter-rouge">play_url</code> as before.</p>
<h2><a class="title-link" name="services" href="#services"></a> Services</h2>
<h3><a class="title-link" name="service-apple_tv_authenticate" href="#service-apple_tv_authenticate"></a> Service <code class="highlighter-rouge">apple_tv_authenticate</code></h3>
<p>To play media on an Apple TV with device authentication enabled (e.g., ATV4 with tvOS 10.2+), Home Assistant must be properly authenticated. This method starts the process and presents the credentials needed for playback as a persistent notification. Please see guide above for usage.</p>
<table>
<thead>
<tr>
<th>Service data attribute</th>
<th>Optional</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code class="highlighter-rouge">entity_id</code></td>
<td>yes</td>
<td>String or list of strings that point at <code class="highlighter-rouge">entity_id</code>s of Apple TVs.</td>
</tr>
</tbody>
</table>
<h3><a class="title-link" name="service-apple_tv_scan" href="#service-apple_tv_scan"></a> Service <code class="highlighter-rouge">apple_tv_scan</code></h3>
<p>Scans the local network for Apple TVs. All found devices are presented as a persistent notification.</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='edit-github'><a href='https://github.com/home-assistant/home-assistant.github.io/tree/current/source/_components/apple_tv.markdown'>Edit this page on GitHub</a></div>
<div class='brand-logo-container section'>
<img src='/images/supported_brands/apple.png' />
</div>
<div class='section'>
IoT class<sup><a href='/blog/2016/02/12/classifying-the-internet-of-things/#classifiers'><i class="icon-info-sign"></i></a></sup>: Local Push
</div>
<div class='section'>
Introduced in release: 0.49
</div>
<div class='section'>
<h1 class='title delta'>Related components</h1>
<ul class='divided'>
<li><a href='/components/media_player.apple_tv/'>
Apple TV Media Player
</a></li>
<li><a href='/components/remote.apple_tv/'>
Apple TV Remote
</a></li>
</ul>
</div>
<div class='section'>
<h1 class="title delta">Category Hub</h1>
<ul class='divided'>
<li>
<a href='/components/apcupsd/'>APCUPSd</a>
</li>
<li>
<a href='/components/abode/'>Abode Home Security</a>
</li>
<li>
<a href='/components/alarmdecoder/'>AlarmDecoder Alarm</a>
</li>
<li>
<a href='/components/amcrest/'>Amcrest IP Camera</a>
</li>
<li>
<a href='/components/android_ip_webcam/'>Android IP Webcam</a>
</li>
<li>
Apple TV
</li>
<li>
<a href='/components/arlo/'>Arlo</a>
</li>
<li>
<a href='/components/axis/'>Axis</a>
</li>
<li>
<a href='/components/wemo/'>Belkin WeMo</a>
</li>
<li>
<a href='/components/blink/'>Blink</a>
</li>
<li>
<a href='/components/bloomsky/'>BloomSky</a>
</li>
<li>
<a href='/components/digital_ocean/'>Digital Ocean</a>
</li>
<li>
<a href='/components/doorbird/'>DoorBird</a>
</li>
<li>
<a href='/components/dyson/'>Dyson</a>
</li>
<li>
<a href='/components/eight_sleep/'>Eight Sleep</a>
</li>
<li>
<a href='/components/emulated_hue/'>Emulated Hue Bridge</a>
</li>
<li>
<a href='/components/enocean/'>EnOcean</a>
</li>
<li>
<a href='/components/ffmpeg/'>FFmpeg</a>
</li>
<li>
<a href='/components/homematic/'>Homematic</a>
</li>
<li>
<a href='/components/tradfri/'>IKEA Trådfri (Tradfri)</a>
</li>
<li>
<a href='/components/isy994/'>ISY994 Controller</a>
</li>
<li>
<a href='/components/insteon_local/'>Insteon (local)</a>
</li>
<li>
<a href='/components/insteon_hub/'>Insteon Hub</a>
</li>
<li>
<a href='/components/insteon_plm/'>Insteon PLM</a>
</li>
<li>
<a href='/components/joaoapps_join/'>Joaoapps Join</a>
</li>
<li>
<a href='/components/juicenet/'>Juicenet</a>
</li>
<li>
<a href='/components/knx/'>KNX</a>
</li>
<li>
<a href='/components/kira/'>Kira</a>
</li>
<li>
<a href='/components/lametric/'>LaMetric</a>
</li>
<li>
<a href='/components/linode/'>Linode</a>
</li>
<li>
<a href='/components/litejet/'>LiteJet</a>
</li>
<li>
<a href='/components/lutron/'>Lutron</a>
</li>
<li>
<a href='/components/lutron_caseta/'>Lutron Caseta</a>
</li>
<li>
<a href='/components/mqtt/'>MQTT</a>
</li>
<li>
<a href='/components/raincloud/'>Melnor Raincloud</a>
</li>
<li>
<a href='/components/microsoft_face/'>Microsoft Face</a>
</li>
<li>
<a href='/components/mochad/'>Mochad</a>
</li>
<li>
<a href='/components/modbus/'>Modbus</a>
</li>
<li>
<a href='/components/mysensors/'>MySensors</a>
</li>
<li>
<a href='/components/neato/'>Neato Robotics</a>
</li>
<li>
<a href='/components/nest/'>Nest</a>
</li>
<li>
<a href='/components/netatmo/'>Netatmo</a>
</li>
<li>
<a href='/components/nuimo_controller/'>Nuimo controller</a>
</li>
<li>
<a href='/components/octoprint/'>OctoPrint</a>
</li>
<li>
<a href='/components/pilight/'>Pilight</a>
</li>
<li>
<a href='/components/qwikswitch/'>QwikSwitch QSUSB Hub</a>
</li>
<li>
<a href='/components/rflink/'>RFLink</a>
</li>
<li>
<a href='/components/rfxtrx/'>RFXtrx</a>
</li>
<li>
<a href='/components/switch.rainbird/'>Rain Bird Switch</a>
</li>
<li>
<a href='/components/ring/'>Ring</a>
</li>
<li>
<a href='/components/scsgate/'>SCSGate</a>
</li>
<li>
<a href='/components/spc/'>SPC</a>
</li>
<li>
<a href='/components/satel_integra/'>Satel Integra Alarm</a>
</li>
<li>
<a href='/components/skybell/'>Skybell</a>
</li>
<li>
<a href='/components/sleepiq/'>SleepIQ</a>
</li>
<li>
<a href='/components/tado/'>Tado</a>
</li>
<li>
<a href='/components/telegram_bot/'>Telegram chatbot</a>
</li>
<li>
<a href='/components/tellstick/'>TellStick</a>
</li>
<li>
<a href='/components/tellduslive/'>Telldus Live</a>
</li>
<li>
<a href='/components/tesla/'>Tesla</a>
</li>
<li>
<a href='/components/thethingsnetwork/'>The Things Network</a>
</li>
<li>
<a href='/components/toon/'>Toon</a>
</li>
<li>
<a href='/components/twilio/'>Twilio</a>
</li>
<li>
<a href='/components/usps/'>USPS</a>
</li>
<li>
<a href='/components/velbus/'>Velbus</a>
</li>
<li>
<a href='/components/velux/'>Velux</a>
</li>
<li>
<a href='/components/vera/'>Vera</a>
</li>
<li>
<a href='/components/verisure/'>Verisure</a>
</li>
<li>
<a href='/components/volvooncall/'>Volvo On Call</a>
</li>
<li>
<a href='/components/wink/'>Wink</a>
</li>
<li>
<a href='/components/xiaomi_aqara/'>Xiaomi Gateway (Aqara)</a>
</li>
<li>
<a href='/components/zwave/'>Z-Wave</a>
</li>
<li>
<a href='/components/comfoconnect/'>Zehnder ComfoAir Q Ventilation</a>
</li>
<li>
<a href='/components/zha/'>Zigbee Home Automation</a>
</li>
<li>
<a href='/components/zoneminder/'>ZoneMinder</a>
</li>
<li>
<a href='/components/ecobee/'>ecobee</a>
</li>
<li>
<a href='/components/gc100/'>gc100</a>
</li>
</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> (no support!).<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>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/docsearch.js/2/docsearch.min.css" />
<script type="text/javascript" src="https://cdn.jsdelivr.net/docsearch.js/2/docsearch.min.js"></script>
<script type="text/javascript">
docsearch({
apiKey: 'ae96d94b201c5444c8a443093edf3efb',
indexName: 'home-assistant',
inputSelector: '#search',
debug: false // Set debug to true if you want to inspect the dropdown
});
document.querySelector('.search .close').addEventListener('click', function(ev) {
ev.preventDefault();
document.querySelector('.search-container').style.display = 'none';
});
document.querySelector('.show-search').addEventListener('click', function(ev) {
ev.preventDefault();
document.querySelector('.search-container').style.display = 'block';
document.getElementById('toggle').checked = false;
document.querySelector('.search-container input').focus();
});
</script>
</body>
</html>