+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. +
+ +To use this component, you must first install some system libraries and a compiler. For Debian or a similar system, this should be enough: + +```shell +$ sudo apt-get install build-essential libssl-dev libffi-dev python-dev +``` + +If you want to automatically discover new devices, just make sure you have `discovery:` in your `configuration.yaml` file. To manually add one or more Apple TVs to your installation, add the following to your `configuration.yaml` file: + +```yaml +# Example configuration.yaml entry +apple_tv: + - host: IP_1 + login_id: LOGIN_ID_1 + name: NAME_1 + start_off: START_OFF_1 + credentials: CREDENTIALS_1 + - host: IP_2 + login_id: LOGIN_ID_2 + name: NAME_2 + start_off: START_OFF_2 + credentials: CREDENTIALS_2 +``` + +Configuration variables: + +- **host** (*Required*): The IP-address of the device. +- **login_id** (*Required*): An identifier used to login to the device, see below. +- **name** (*Optional*): The name of the device used in the frontend. +- **start_off** (*Optional*): Set to true if device should start in fake standby. +- **credentials** (*Optional*): Credentials used for AirPlay playback. + +In order to connect to the device you need a *login id*. The easiest way to obtain this identifier is to use the `apple_tv_scan` service (described below). Additional information about `start_off` and `credentials` can also be found under the guides section. + +## {% linkable_title Guides %} + +### {% linkable_title Scanning for devices %} + +To scan for devices, press the icon in the upper left corner and select the leftmost icon according to the image: + +
+
+Select `apple_tv` as domain and `apple_tv_scan` as service then press the button:
+
+
+
+Scanning will be done for three seconds and notification will be shown in the state view with all found devices:
+
+
+
+Alternatively you may use the application ``atvremote``. Install it with ``pip3 install --upgrade pyatv`` in your Home Assistant environment (note: do *not* use sudo). Then run ``atvremote scan`` to scan for all devices (try again if a device is missing):
+
+```bash
+$ atvremote scan
+Found Apple TVs:
+ - Apple TV at 10.0.10.22 (login id: 00000000-1234-5678-9012-345678901234)
+
+Note: You must use 'pair' with devices that have home sharing disabled
+```
+
+Just copy and paste the login id from the device you want to add. For more details about `atvremote`, see: [this page](http://pyatv.readthedocs.io/en/master/atvremote.html).
+
+### {% linkable_title My Apple TV turns on when I restart Home Assistant %}
+
+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.
+
+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. There's also no known way to turn off the Apple TV via the procotol used for communication. You basically have the following options:
+
+- Do not use this platform
+- Disable HDMI CEC on your Apple TV
+- Use "fake standby"
+
+The first two points are quite obvious. Fake standby is a concept implemented in this platform that disables all requests to the device and make 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 using an automation with `turn_on`. To make it more useful, you can write automations that turns it on or off depending on some other device, like the input source on your receiver.
+
+To put a device into fake standby when starting Home Assistant, add `start_off: true` to your configuration.
+
++Turning the device on/off in the user interface will *not* turn the physical device on/off according to description above. +
+ + +### {% linkable_title Setting up device authentication %} + +If you, when playing media with `play_url`, get the following error message: + +*“This AirPlay connection requires iOS 7.1 or later, OS X 10.10 or later, or iTunes 11.2 or later.”* + +then device authentication is required. Press the icon in the upper left corner and select the leftmost icon according to the image below: + +
+
+Select `apple_tv` as domain, `apple_tv_authenticate` as service and enter `{'entity_id': 'XXX'}` into "Service Data", but replace XXX with the entity id of your device (e.g. `media_player.apple_tv`). Press the button and hopefully you are presented with an input dialog asking for a pin code:
+
+
+
+If no dialog appears, go back to the states view and display it from there (press `CONFIGURE` as displayed in the image):
+
+
+
+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 ``credentials:`` with no line-break:
+
+```yaml
+# Example configuration.yaml entry
+apple_tv:
+ - host: 10.0.0.20
+ login_id: 00000000-1234-5678-9012-345678901234
+ credentials: 1B8C387DDB59BDF6:CF5ABB6A2C070688F5926ADB7C010F6DF847252C15F9BDB6DA3E09D6591E90E5
+```
+
+Restart Home Assistant and you should now be able to use `play_url` as before.
+
+## {% linkable_title Services %}
+
+### {% linkable_title Service `apple_tv_authenticate` %}
+
+In order to play media on an Apple TV with device authentication enabled (e.g. ATV4 with tvOS 10.2+), Home Assistant must properly authenticated. This method starts the process and presents the credentials needed for playback as a persistent notification. Please see guide above for usage.
+
+| Service data attribute | Optional | Description |
+| ---------------------- | -------- | ----------- |
+| `entity_id` | yes | String or list of strings that point at `entity_id`s of Apple TVs.
+
+### {% linkable_title Service `apple_tv_scan` %}
+
+Scans the local network for Apple TVs. All found devices are presented as a persistent notification.
+
diff --git a/source/_components/media_player.apple_tv.markdown b/source/_components/media_player.apple_tv.markdown
index 9b49da82a6c0..3fd91fbe0a35 100644
--- a/source/_components/media_player.apple_tv.markdown
+++ b/source/_components/media_player.apple_tv.markdown
@@ -9,43 +9,8 @@ sharing: true
footer: true
logo: apple.png
ha_category: Media Player
-ha_iot_class: "Local Polling"
+ha_iot_class: "Local Push"
ha_release: 0.38
-featured: true
---
-The `apple_tv` platform allows you to control an Apple TV (3rd and 4th generation).
-
--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. -
- -If you want to automatically discover new devices, just make sure you have `discovery:` in your `configuration.yaml` file. To manually add an Apple TV to your installation, add the following to your `configuration.yaml` file: - -```yaml -# Example configuration.yaml entry -media_player: - - platform: apple_tv - host: IP_ADDRESS - login_id: LOGIN_ID -``` - -Configuration variables: - -- **host** (*Required*): The IP-address of the device -- **login_id** (*Required*): An identifier used to login to the device, see below -- **name** (*Optional*): The name of the device used in the frontend - -In order to connect to the device you need a *login id*. The easiest way to obtain this identifier is to use the application ``atvremote``. It should be available in the same environment as you installed Home-Assistant. To install this utility, run ``pip3 install --upgrade pyatv``. The run atvremote scan for all devices (try again if a device is missing): - -```bash -$ atvremote scan -Found Apple TVs: - - Apple TV at 10.0.10.22 (login id: 00000000-1234-5678-9012-345678901234) -``` - -Just copy and paste the login id from the device you want to add. For more details about `atvremote`, see: [this page](https://github.com/postlund/pyatv/blob/master/docs/atvremote.rst). - -## {% linkable_title Notes and Limitations %} - -- Pairing is currently not supported +To setup the `apple_tv` platform, please follow the instructions on the [Apple TV Component page](/components/apple_tv/). diff --git a/source/_components/remote.apple_tv.markdown b/source/_components/remote.apple_tv.markdown new file mode 100644 index 000000000000..e1bba9e06599 --- /dev/null +++ b/source/_components/remote.apple_tv.markdown @@ -0,0 +1,44 @@ +--- +layout: page +title: "Apple TV" +description: "Instructions how to integrate Apple TV remote into Home Assistant." +date: 2017-06-26 20:50 +sidebar: true +comments: false +sharing: true +footer: true +logo: apple.png +ha_category: Remote +ha_iot_class: "Local Push" +ha_release: 0.49 +--- + + +The `apple_tv` remote platform allows you to send remote control buttons to an Apple TV. It is automatically setup when an Apple TV is configured, please see [Apple TV Component](/components/apple_tv/) for configuration details. + +At the moment, the following buttons are supported: + +- up +- down +- left +- right +- menu +- top_menu +- select + +A typical service call for press several buttons looks like this. + +```yaml +service: remote.send_command +data: + entity_id: remote.apple_tv + command: + - left + - left + - menu + - select + device: '' + +``` + +Please note that `device` must be specified (because of validation) but is not used by this platform. So you may specify any value. diff --git a/source/images/components/apple_tv/auth_pin.jpg b/source/images/components/apple_tv/auth_pin.jpg new file mode 100644 index 000000000000..b87b2a7d6ca5 Binary files /dev/null and b/source/images/components/apple_tv/auth_pin.jpg differ diff --git a/source/images/components/apple_tv/auth_start.jpg b/source/images/components/apple_tv/auth_start.jpg new file mode 100644 index 000000000000..6a35609c9962 Binary files /dev/null and b/source/images/components/apple_tv/auth_start.jpg differ diff --git a/source/images/components/apple_tv/scan_result.jpg b/source/images/components/apple_tv/scan_result.jpg new file mode 100644 index 000000000000..0051f451666f Binary files /dev/null and b/source/images/components/apple_tv/scan_result.jpg differ diff --git a/source/images/components/apple_tv/scan_start.jpg b/source/images/components/apple_tv/scan_start.jpg new file mode 100644 index 000000000000..2b40fbf2265b Binary files /dev/null and b/source/images/components/apple_tv/scan_start.jpg differ