Apple TV Control Driver v1.10

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, a browse menu system with real app icons, and a full browser-based Web Object control UI.

When enabled, the optional Full Crypto Offload setting routes the heavy SRP / Ed25519 / Curve25519 cryptography to a cloud server so the driver can pair successfully on older RTI processors –including the XP-3 and XP-6 which cannot complete the local crypto in time before the Apple TV's pairing session times out. On XP-8v and XP-6s this setting is left off by default and all cryptography runs locally.

Upgrading from v1.08

If you're upgrading from v1.08, your driver will keep behaving exactly as it does today –both new optional features (Cloud Crypto Offload and Web Object Enabled) default to OFF. The only things you'll get automatically are bug fixes (screensaver sends HID 11 now, debug-off is silent, etc.). Your existing pairing credentials and licence key carry over.

To unlock the new pairing flow on XP-6 / XP-3, flip Full Crypto Offload to True under the Pairing category. To enable the browser remote, flip Web Object Enabled to True under the Polling category.

What's New in v1.10

- Pairing works on every XP processor via opt-in cloud crypto offload –flip the Full Crypto Offload config setting to enable. Confirmed working on XP-8v, XP-6s, and XP-6. XP-3 and XP-8s are still to be confirmed (TBC).

- Browser-based Web Object UI with apps, now-playing, remote controls, on-screen keyboard, system + pairing tabs, live status, theme picker, and licence/trial display

- Driver to server WebSocket bridge replaces 1-second HTTP polling –dramatically less processor stress and sub-100ms command latency

- Soft keyboard tab with text input field auto-launches when a text field is focused on the Apple TV; whole-string batch send (one round-trip, not one per character)

- App Switcher via double-tap Home; close cards with Up pressed twice (documented below)

- Screensaver button now uses HID 11 (dedicated screensaver) instead of HID 12 (sleep) –fixes the long-standing "screensaver = sleep" bug

- DebugLevel = Off is now actually quiet –every non-error log line is gated by the DebugLevel config setting. ERRORs, warnings, trial state, and licence state always print so installers can still diagnose problems

- Display Options in the Web UI Settings let users toggle which tabs are visible per browser (saved to localStorage), independent of the IDesign defaults

- Live pairing-progress banner on the Pair tab showing what's happening at every step of pair-setup and pair-verify

Requirements

1. Apple TV HD (4th gen, A1625) or Apple TV 4K (any generation, A1842/A1962/A2169/A2737/A3253) running tvOS 15 or later

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

3. Internet access on the RTI processor's network is only required if you enable the Full Crypto Offload setting (needed for pairing on XP-3 / XP-6 and recommended for reconnects on those older processors). On XP-8v and XP-6s the default settings perform all cryptography locally and no internet is needed. The Web Object UI also requires internet when enabled, since it routes through shpdrivers.services.

Processor Compatibility (v1.10):

- XP-8v –working

- XP-6s –working

- XP-6 –working with Full Crypto Offload enabled (pair-setup ~20s, well inside Apple TV's 30s session timeout)

- XP-3 –to be confirmed (TBC)

- XP-8s –to be confirmed (TBC)

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

Web Object UI

A browser-based control UI is available at:

https://shpdrivers.services/atvdev/?mac=<PROCESSOR-MAC>

The Web Object is designed to be embedded in any RTI panel template that supports a Web Object widget, or opened in any browser (iPad / iPhone / Android / desktop).

Tabs:

- Controls –D-Pad, Menu/Home/App Switcher, Play/Pause, Volume, Siri

- Apps –All installed apps with real icons; tap to launch. Current app is highlighted.

- Keyboard –Large text input + Send button. Auto-jumps here when the Apple TV reports a text field is focused. (On iOS Safari, the device's soft keyboard requires one tap on the input field –this is an Apple restriction that no website can bypass.)

- System –Sleep, Wake, Screensaver, Refresh Apps

- Pair –Live progress banner, step-by-step instructions, PIN entry. The banner shows exactly what the driver is doing at every stage (Connecting / Pairing / Computing proof / Signing M5 / Verifying M6 / Paired).

Settings (gear icon, top-right):

- Licence –Shows Licensed / Trial / Trial expired plus remaining trial minutes

- MAC –The processor's MAC address (this is the licence key target)

- Display Options –Per-browser toggles for which tabs are visible. Saved to localStorage so each user can customise their own view without changing the driver-wide defaults set in IDesign.

- Theme –6 preset themes + a custom colour picker

The Web Object can be disabled entirely from the driver config ("Web Object Enabled" setting) for installations that want to use only the native browse menu.

App Switcher (Double-Tap Home)

The driver supports double-tapping the Home button to open the App Switcher overlay on tvOS, matching the Siri Remote behaviour.

- Open App Switcher: Send the "Home Double Tap" function (or tap the dedicated button in the Web Object UI).

- Navigate between apps: Use Left / Right.

- Close the highlighted app: Press Up twice. The first Up press selects the close gesture on the highlighted card; the second Up confirms the close. This matches Apple's Siri Remote swipe-up behaviour.

- Exit App Switcher: Press Menu or Home once to return to the prior screen.

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.10 –Cloud crypto offload (opt-in, enables pairing on XP-3 / XP-6); browser-based Web Object UI (opt-in, controls + apps + keyboard + system + pairing + theme picker); persistent driver-server WebSocket; live pairing-progress banner; transport controls (Play / Pause / Skip 10s); Screensaver button now sends HID 11 (was Sleep / HID 12); DebugLevel=Off now actually silences operational logging; App Switcher fix; live trial-timer refresh; Settings modal with per-browser display-option toggles. All new features default OFF –existing v1.08 installs behave identically until the integrator opts in.

- 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.