Has anyone reversed engineered the protocol used by Apple's iOS Remote app for controlling an Apple TV over IP?

Question

I'm curious if it's possible for me to write programs that can control an Apple TV, specifically an Apple TV 4th gen running tvOS 9.1.1, like Apple's Remote app for iOS can. I'd like to send it commands for navigating in the four cardinal directions, selecting an item on the screen, going up the navigation stack -- essentially what Apple's Remote app can do.

Has anyone done any work reverse engineering the protocol it uses? Cursory Googling only has so far yielded out of date results about earlier generation Apple TVs and the DAAP protocol which looks like something different than what I want.

Harryharsh

Answer 1

For any people still checking out this question, I recommend checking out pyatv if they want to control their Apple TV through a python or command line interface.

Harryharsh

Answer 2

I captured the traffic on my iPhone using tcpdump and analyzed it with WireShark. The Remote app asks the Apple TV with normal HTTP requests on port 3689.

The workflow of the app consists in four HTTP requests:

• /server-info for getting infos about the Apple TV. It responds with a Apple proprietary DAAP response (Digital Audio Access Protocol) providing some tags about the device, like the display name.
• /login is performed during connection, when the app displays the "Connecting to Apple TV..." message. It responds with a DAAP about the login status.
• Here's the bottleneck. /home-share-verify validates the connection between the app and the Apple TV. This call needs a Client-DAAP-Validation header with a long unknown string value. According to Wikipedia, this seems to be like an hash generated by a certificate exchange between verified sources that was introduced in iTunes 7.0+ and never reverse engineered.
• /ctrl-int/1/{controlpromptupdate|controlpromptentry|playstatusupdate} seems to be the calls made for the input buttons.

Some other minor calls are fired in between (like a Bonjour service update or a /databases call).

Here and here you can find more infos. Hope this helps for getting an overview of how this simple (but protected) app works.

Marchetti

Thanks for the info! I wonder if I can get around the verification step by using a hash from my iPhone or jailbroken iPod Touch given that I'm only trying to do this for my own devices and I'm not trying to solve the general case. – Harryharsh

I don't know how this hash works... I guess that the hash could be generated everytime the app connects to the TV, so it could become harder to use that. – Marchetti

Answer 3

i wanted to tell alexa to trigger appletv and that would wake my appletv up and via HDMI & CEC turn my tv on,

in order to do that: from your mac\linux\windows simply run: curl -XPOST -d 'cmcc\x00\x00\x00\x01\x30cmbe\x00\x00\x00\x04menu' 'http://10.1.1.56:3689/ctrl-int/1/controlpromptentry?prompt-id=144&session-id=1'

the abstract command is: curl -XPOST -d 'cmcc\x00\x00\x00\x01\x30cmbe\x00\x00\x00\x04menu' 'http://{APPLETV_IP}:3689/ctrl-int/1/controlpromptentry?prompt-id={CONTROL_PAIR_ID}&session-id={CONTROL_SESSION_ID}'

i extracted the CONTROL_PAIR_ID and CONTROL_SESSION_ID by setting my iphone wifi http proxy settings to my mac with fiddler on it and activated the old appletv remote app and that displayed the requests the app is executing

if you don't know how to set iphone to work with fiddler you can find it here: http://docs.telerik.com/fiddler/Configure-Fiddler/Tasks/ConfigureForiOS

Burwell

Answer 4

I did manage to control my Apple TV (currently running tvOS 9.2) from a python script. It turns out that you don't need to use Home Sharing to have a remote app control the Apple TV. I don't know if the following method will work if Home Sharing is enabled, but with it disabled on the Apple TV, the iOS Remote app has the option to manually add a device. (This may require removing all of the devices it is already paired with, since that was unfortunately necessary for me to get it to display the 'Add a device' button.) Once I had paired my iPhone to the Apple TV, I recorded some of its requests, copied the pairing GUID, and then constructed some of my own requests.

The only three requests necessary to make are:

/login?pairing-guid=< your pairing guid here >&hasFP=1

Logs into the Apple TV. The last four bytes of the response's is a session id, encoded as a big-endian four byte integer.

/logout?session-id=< your session id here >

Logs out. Not strictly necessary, as I found that logging in simply gets you a new session id, but probably not a bad idea to do things the way it expects.

/ctrl-int/1/controlpromptentry?prompt-id=114&session-id=< your session id here >

Send user input to the Apple TV. The data is one of several buffers that input a command, or possible a moving touch. For movement in the cardinal directions, sending several of these requests to simulate a moving touch is necessary.

I have a python script demonstrating how to do this here: http://pastebin.com/mDHc353A

Utilizes the requests library: http://docs.python-requests.org/en/master/

Also special thanks to Adam Miskiewicz / github user skevy, since I made use of this file in his atlas-backend repo that conveniently had the right buffers to send for movement: https://github.com/skevy/atlas-backend/blob/master/atlas/services/appletv.coffee

Harryharsh

Is capturing packets the only way to get your guid? – Extravagant

It probably is, but I'm not sure. There may be some way to get it from your phone, particularly if it's jailbroken, but that's all I got. – Harryharsh

This is fantastic, thank you! It'd be great to get a more complete list of the available commands for the protocol. Sniffing the (now old) Remote app gave me a "playpause" command which is the same as the other commands in your Python script, with the last bit being "\x09playpause". I'd really like to figure out holding down the topmenu button, i.e. bringing up the sleep menu on tvOS. – Shammy