Apple TV Control Driver v1.09

Smart Home Programming

Overview

This driver controls Apple TV (tvOS 15+) using the Companion Protocol over TCP/IP. It supports navigation, media control, volume, power, app launching, text input, and a browse menu system with real app icons. All pairing and encryption is handled directly by the driver –no proxy server or additional hardware is required.

Requirements

1. Apple TV HD (4th gen) or Apple TV 4K running tvOS 15 or later

2. Apple TV must be on the same network as the RTI processor

3. RTI XP-8 processor with runtime v14 or later

4. Internet access on the RTI processor's network is required for pairing and recommended for reconnections (cryptographic computation is offloaded to a cloud server). After the session is established, all commands are local –no internet needed.

Setup Instructions

Step 1: Find the Apple TV IP address

On Apple TV: Settings > Network > Wi-Fi > select your network > note the IP address

Or check your router's DHCP client list for the Apple TV

We recommend setting a static IP or DHCP reservation

Step 2: Configure the driver

Enter the Apple TV IP address in the "Apple TV IP Address" setting

Companion port is 49153 by default (change only if needed)

Step 3: Pair the driver with your Apple TV

The driver will automatically attempt to connect on startup

Navigate to the Pairing menu in the browse menu and tap "Start Pairing"

A 4-digit PIN will appear on the Apple TV screen

Enter the PIN using the digit buttons or the "Submit PIN" function

Pairing credentials are stored permanently –this only needs to be done once

Step 4: Verify the connection

After successful pairing, the driver auto-connects on startup

Check the "Connection Status" variable –it should show "Connected"

Try sending a navigation command (DPad Up/Down/Left/Right, Select)

Features

Navigation & Media Control

D-Pad navigation (Up, Down, Left, Right, Select)

Menu / Back, Home

Play, Pause, Play/Pause, Next, Previous, Fast Forward, Rewind

Volume Up, Volume Down, Mute

Channel Up/Down, Page Up/Down, Guide

App Launching

Browse and launch installed apps from the Apps menu

48 pre-configured app launch shortcuts for use in macros (Netflix, Disney+, Prime Video, YouTube, Stan, Binge, Kayo, ABC iView, SBS, 7plus, 9Now, 10 Play, and more)

Launch any app by bundle ID using the "Launch App" function

Current app indicator (✓ shown in the apps list

Real app icons from the Apple App Store displayed in browse menus

Text Input / Keyboard

"Send Text" function sends text to the Apple TV when a text field is focused (e.g., search)

"Keyboard Active" variable indicates when the Apple TV has a text input field focused

Use Show/Hide Keyboard functions to control keyboard panel visibility on the RTI interface

Feedback Variables

Volume –Current volume level (0-100%)

Current App –Bundle ID of the currently running app

Current App Name –Friendly name of the current app

Current App Icon –App icon image for display on RTI interfaces

Screen State –Awake, Asleep, or Screensaver

Keyboard Active –True when Apple TV has a text input field focused

Connected –Connection state (boolean)

Paired –Pairing state (boolean)

Power Control

Sleep, Wake, and Screensaver commands

Browse Menu

The browse menu provides access to:

Apps –View and launch installed apps with real icons

Controls –Play/Pause, Volume, Home, Menu

System –Sleep, Wake, Screensaver, Refresh Apps, Device Info

Pairing –Start pairing, enter PIN, clear pairing

Each menu section can be enabled or disabled in the driver configuration.

App Launch Shortcuts

The following app launch shortcuts are available as macro commands in Integration Designer:

Netflix, Disney+, Prime Video, YouTube, Apple TV+, Apple Music, Spotify, Plex

Stan, Binge, Kayo, ABC iView, SBS, 7plus, 9Now, 10 Play

Paramount+, HBO Max, Hulu, Peacock, Tubi, BritBox, hayu, Foxtel, FreeView

Twitch, DAZN, Crunchyroll, ESPN, Pluto TV, discovery+, STARZ, Fubo

YouTube Kids, YouTube Music, YouTube TV, Infuse, VLC, Jellyfin

Apple Fitness+, Apple Podcasts, Sling TV, Amazon Music, TIDAL

MUBI, CNN, CuriosityStream, Peloton

Debug Console

Connect via telnet to the debug port (default 12505) for testing:

telnet <processor-ip> 12505

Available commands:

help –List all commands

status –Show connection state and device info

connect / disconnect –Manual connection control

pair –Start pairing process

pin XXXX –Submit 4-digit PIN

button <1-19> –Send HID button code

app <bundle.id> –Launch app by bundle ID

apps –List installed apps

crypto <test> –Run crypto verification test

Troubleshooting

"Not Paired" status –Navigate to the Pairing menu, tap Start Pairing, and enter the PIN shown on the Apple TV.

Pairing fails –Ensure the Apple TV is awake and on the home screen. Try again with the correct PIN. The PIN changes each time.

Connection drops –The driver auto-reconnects up to 3 times. If the Apple TV is asleep, send the Wake command first.

Commands not working –Verify the connection status is "Connected". Some commands only work when awake.

Apps list empty –Wait a few seconds after connecting. Use Refresh App List to manually update.

Volume not updating –Volume feedback requires a volume-capable app to be running. The driver auto-detects when volume control is available.

Protocol Notes

The driver uses the Apple TV Companion Protocol which provides:

Volume level feedback (polled when available)

Power/screen state (push events)

Current app detection (push events)

Text input/keyboard focus detection (push events)

App launching and installed app list

Note: Now playing metadata (track title, artist, album, duration) is not available through the Companion Protocol. That data requires the separate MRP (Media Remote Protocol) which uses protobuf encoding.

Licensing

This driver is sold through the Smart Home Programming Driver Store.

Driver Store: https://shpdrivers.services/store/

Your Account: https://shpdrivers.services/store/account.html

Free Trial:

The driver operates in a 120-minute trial mode without a licence key. The trial provides full functionality and resets each time the RTI processor is rebooted.

To Purchase:

1. Create an account at https://shpdrivers.services/store/

2. Add this driver to your cart

3. Enter your RTI processor MAC address during checkout

4. Complete payment and receive your licence key by email

5. Enter the licence key in the driver configuration

Support

For bug reports, technical support, or feature requests, please use the ticket system in your account at the Driver Store.

Store: https://shpdrivers.services/store/

Email: david@smarthomeprogramming.com.au

Version History

v1.09 –Fixed Browse tag mapping (Select Item), added Menu buttontag, debug console version sync

v1.08 –Standardised licensing and support sections, encrypted packaging

v1.06 –48 app launch shortcuts (20 new), SRP server pairing, default port 49153, auto-navigate home after pairing, internet requirement documented, licensing/support info

v1.04 –Added 28 app launch shortcuts for macros, volume feedback, keyboard active variable, text input support, hayu/Foxtel/ESPN/discovery+/STARZ/Fubo icons, removed Siri, app clears on Home press

v1.03 –Real iTunes app icons for 35+ apps, current app icon image variable, tick beside current app, pairing UX improvements

v1.02 –Browse menus, app launching, screen state feedback, debug console

v1.01 –SRP pairing via HTTP proxy, connection management

v1.00 –Initial release with full crypto stack and companion protocol

Terms of Service

All drivers are provided "as is" without warranty of any kind. You use this software entirely at your own risk. A free trial is included so you can verify compatibility with your system before purchasing – do not purchase a licence if you have not tested the driver on your hardware. For full terms including warranty disclaimer, limitation of liability, and refund policy, visit:

https://smarthomeprogramming.com.au/store/terms.html

Copyright 2026 Smart Home Programming. All rights reserved.