Apple TV by Papaya | Docs

Driver name in Composer: Apple TV. Model: Apple TV by Papaya. File: Papaya_AppleTV.c4z. Current driver version: 1.9.15 (shown in the Driver Version property). Store slug: apple-tv. The Apple TV license also covers the Streaming Search and Custom Mini App drivers on the same project.

Overview

The Apple TV driver controls an Apple TV straight from the Control4 controller over the network. It uses Apple's Companion protocol, the same encrypted link the iPhone Remote app uses. No bridge, Raspberry Pi or other box is needed.

What it does:

Full remote over IP: arrows, Select, Menu, Home, Play/Pause, skip, scan, channel and page keys.
App tiles: hosts Control4's Universal mini app drivers (Netflix, YouTube, Disney+ and so on). Each app gets its own tile in the room and opens on the Apple TV when picked.
Deep links: the OPEN_LINK command takes a normal web link to a show or movie and opens that title in the right app, where the app supports it.
Live status: Power State (Awake, Screensaver, Asleep) and Play State (Playing, Paused, Stopped), with events and variables.
Wake on use: wakes a sleeping Apple TV before every app launch and when the room turns on. No "press Menu on select" programming needed.
Finds itself: discovers Apple TVs on the network and follows the paired one if its IP changes. The Companion port changes on every Apple TV reboot; the driver finds it automatically.
Optional IR backup or IR-only control.
One binding: HDMI Out carries audio and video for the Apple TV and every app tile.

Who it is for: dealers who want a better Apple TV experience than a plain IR or remote-only driver, with app tiles in the Watch menu and no extra hardware.

Requirements

Control4 OS 3.4.1 or newer (the driver's minimum). It was developed and tested on OS 4.x.
Apple TV HD or Apple TV 4K on tvOS 15 or newer.
Apple TV on the same network and VLAN as the controller.
On the Apple TV: Settings > AirPlay and HomeKit > Allow Access set to Everyone on the Same Network (the default).
Discovery uses Bonjour (mDNS). If multicast is blocked or the Apple TV is on another VLAN, type the IP by hand.
A DHCP reservation for the Apple TV is still good practice, even though the driver follows IP changes.
For IR modes only: a controller IR port and an emitter on the Apple TV.
Deep links and app launching need IP control. They do not work in IR only mode.

Installing and first setup

In Composer Pro, add Apple TV by Papaya (search "Papaya" or "Apple TV") to the room where the Apple TV is. It adds two devices: Apple TV (the source) and App Switcher (hosts the app tiles, hidden from the room list).
Connections: bind Apple TV > HDMI Out to the HDMI input on the TV, receiver or matrix the Apple TV plugs into. This is the only required binding.
Properties: open the Apple TV list and pick your Apple TV. If the list is empty, run the Find Apple TVs action, or type the IP into Apple TV IP Address.
Make sure the Apple TV is awake and showing a picture. Run the Start Pairing (shows PIN on TV) action. A 4-digit PIN appears on the TV.
Type the PIN into Pairing PIN and press Set. The PIN clears itself, Paired Apple TV shows the Apple TV's name and ID, and Status changes to Connected.
Optional app tiles: add the Control4 Universal mini app drivers you want (search "Universal", for example Netflix (Universal)) and bind each one to a MiniApp input on the App Switcher.
Refresh Navigators. Test the Apple TV source and each tile with the remote.

Pairing survives reboots, power cuts and driver updates. You pair once per driver instance. After adding the driver or changing bindings, select the Apple TV or a tile once so Director recalculates the room paths.

Pairing Name (default Control4) is the name shown on the Apple TV under Settings > Remotes and Devices.

Properties

Status and info properties

Driver Version: installed version.
Status: connection state, for example Connected (port 12345), Offline: ..., or a pairing prompt.
Power State: Awake, Screensaver or Asleep, live from the Apple TV.
Play State: Playing, Paused or Stopped.
Apple TV Model / tvOS Version: read from the network when the Apple TV is found.
Last Error: the most recent failure with date and time. Cleared on the next good connection.
Apple TVs Found: result of the last network search.
Paired Apple TV: name and ID of the paired Apple TV, or Not paired.
Tile Remote Keys: the last room whose app tile was given a key route to the Apple TV.
Installed Apps: count of apps read from the Apple TV. The full list prints in the Lua tab.
Mini App Log: last tile selection or link and what happened.
Last App / Last Bundle ID: last app requested and the tvOS bundle ID it opened (UNKNOWN if not found).
Self-Test: result of the crypto self-test.

Connection and pairing properties

Control Mode: IP (default), IP with IR backup, or IR only. See Connections.
Apple TV: list of Apple TVs found. Default Manual (use IP Address below). Picking one fills in the IP.
Apple TV IP Address: filled in when you pick an Apple TV. Type it only for a manual setup.
Pairing Name: default Control4. Name shown on the Apple TV's Remotes and Devices list.
Pairing PIN: type the PIN from the TV after Start Pairing.
Ethernet MAC (Wake-on-LAN): optional. From Apple TV Settings > General > About > Ethernet Address. Lets the driver send Wake-on-LAN when the Apple TV does not answer. Ethernet only.
Wake Apple TV: On (default) sends Wake before every launch. Off launches without waking.
Debug Mode: Off (default) or On. On prints every step to the Lua tab. Turns itself off after 45 minutes.

Behavior properties

After App Launch: Stay on app tile (default; the room keeps the tile, such as Netflix, as its source) or Switch room to this Apple TV (half a second after launch the room source changes to the Apple TV device, like Passthrough Mode Off on Control4's Roku driver).
Auto-Press Open: On/Off, default Off. After a deep link, presses Select to clear the "Open in (app)?" prompt that Prime Video and Paramount+ show.
Auto-Pick Profile: On/Off, default Off. After a launch or deep link, presses Select on the "Who's Watching?" screen to pick the highlighted profile.
Auto-Advance Speed: Normal (default) or Slow. Slow lengthens the auto-press delays for a slower network or Apple TV. Auto-press is timing based and skipped in IR only mode.
On Apple TV Select: Go to Home screen (default) or Do nothing, when a room selects the Apple TV source itself.
Info Button: Open Settings (default) or TV button.
Guide Button: App switcher (default) or Guide (plain Guide key for live TV apps).
On Room Off: Sleep the Apple TV (default) or Leave the Apple TV on.
Skip Seconds: 10 (default), 15 or 30.
Test App: app name or bundle ID used by the Test Launch action. Default Netflix.

Actions

Find Apple TVs: search the network again and refresh the Apple TV list.
Start Pairing (shows PIN on TV): shows a PIN on the TV to pair this driver.
Forget Pairing: deletes the stored pairing keys. To remove it on the Apple TV side too, delete it under Remotes and Devices.
Reconnect: drops the connection and opens a fresh one.
Refresh Installed Apps: reads the installed app list from the Apple TV again. Prints Name=bundle.id for every app in the Lua tab.
List Connected Mini Apps: prints each bound tile and the app it will open.
Test Launch: opens the Test App now.
Wake Apple TV / Sleep Apple TV: wake or sleep now.
Restart Apple TV: restarts over IR only. Needs IR Output bound. Without it, Status says so and nothing is sent.
Run Crypto Self-Test: checks the controller's encryption functions against known values.

Programming

Commands

Found under the Apple TV's Device Actions in Programming.

LAUNCH_APP (App Name): opens an app by name (Netflix, Plex) or by tvOS bundle ID. Wakes the Apple TV first.
OPEN_LINK (Link): opens a specific title from a normal web link. See Deep links below.
SEND_KEY (Key): Up, Down, Left, Right, Select, Menu, Home, PlayPause, Wake, Sleep, HomeScreen, AppSwitcher, Settings, SkipFwd, SkipBack, Screensaver, Siri, Guide.
WAKE, SLEEP: wake or sleep the Apple TV.
RESTART: IR reboot code out IR Output. For a nightly restart, power-cycling the outlet is more dependable.

The Apple TV also takes the standard Control4 media player commands (UP, DOWN, ENTER, MENU, PLAY, PAUSE, ON, OFF and so on), so Navigators, SR260/Halo remotes and keypads work as usual.

Events, variables and conditionals

Events: App Launch Requested, Unknown App (the app is not on this Apple TV), Playing, Paused, Stopped, Woke Up, Screensaver Started, Went To Sleep.

Variables: SCREEN_STATE (Awake, Screensaver, Asleep), PLAY_STATE (Playing, Paused, Stopped), CURRENT_APP (last app the driver opened). The driver also publishes PAPAYA_ROOM and PAPAYA_ROOM_ID (its own room) for the Streaming Search driver.

Conditionals: none.

Examples:

Keypad button opens Plex: Room > Select Video Device > Apple TV, then Apple TV > LAUNCH_APP > App Name = Plex.
Goodnight: Apple TV > SLEEP (Room Off already does this when the Apple TV is in use).
Missing app alert: on Unknown App, send a push notification.

Deep links

Paste an ordinary web URL into the Link field. The driver turns it into the app's own link. Hardware-tested on current tvOS (November 2026):

Opens the exact title with no prompt: Apple TV+ (tv.apple.com links), Disney+, Peacock, Pluto TV.
Opens the exact title after a one-tap "Open" prompt: Prime Video (any link with an amzn1.dv.gti ID), Paramount+, YouTube (youtube.com/watch, youtu.be, shorts). Turn on Auto-Press Open to skip the tap.
App launch only (opens the app home, not the title): Netflix (Netflix dropped tvOS deep links in its Sept 2025 update), Hulu, Max. Also Starz, Discovery+, AMC+, Tubi, ESPN, Plex, Spotify and live TV services.
Crunchyroll, MGM+, Shudder, HiDive, MUBI, Criterion Channel, Acorn TV, NBC, PBS and Xumo Play links are tried, but not confirmed on hardware. If tvOS rejects the link the driver opens the app instead.
Anything else starting with scheme:// or https:// is passed to the Apple TV unchanged.

The target app must be installed. Mini App Log shows what the driver did with each link.

Connections and bindings

HDMI Out (Apple TV): bind to the HDMI input the Apple TV plugs into. Required. Carries audio and video.
MiniApp 1 to MiniApp 25 (App Switcher): bind Universal mini app drivers or Papaya Custom Mini App tiles, one per input. Optional.
IR Output (Apple TV): bind to a controller IR port with an emitter on the Apple TV. Only for IR modes.
RCA Audio Out, Optical Audio Out (Toslink), Digital Coax Audio Out: only when an HDMI audio extractor sends the Apple TV's sound to a separate audio input. Leave unbound otherwise.
Apple TV Discovery (mDNS): network binding the driver uses for Bonjour. No action needed.
Hidden links join the App Switcher to the Apple TV so every tile goes out HDMI Out. Composer creates them when the driver is added. You cannot see or delete them.

How tile remote keys work: Universal mini apps send remote keys along the room's audio path, and Director never builds one for a mini app tile. Whenever a room is on one of this driver's tiles, the driver writes the tile's path into the room so the keys reach the Apple TV. Nothing to bind or program.

Control Mode and IR:

IP: everything over the network. IR Output is not used.
IP with IR backup: network first. If the link is down, keys, Wake and Sleep go out IR right away while the driver reconnects.
IR only: keys, Wake and Sleep over IR. No pairing needed. Tiles only wake the Apple TV; they cannot open apps.

IR uses Apple's standard remote codes (Up, Down, Left, Right, Select, Menu, Play/Pause, power on and off), no learning needed. IR cannot open apps, send the TV button, Guide, channel or page keys.

Best practices

Bind only HDMI Out. Do not add extra audio bindings unless you use an HDMI audio extractor.
Give the Apple TV a DHCP reservation and keep it on the controller's VLAN.
Leave Wake Apple TV On. Leave the Apple TV on its normal sleep timer; Sleep After does not need to be Never.
For typing, searches and passwords, have the customer use the Apple TV Remote in iPhone/iPad Control Center. The Control4 apps only send finished text, so live typing from Control4 is not possible.
For a reliable restart, put the Apple TV on a smart outlet (WattBox or similar) and power-cycle it from programming. Network restart is not possible on Apple TV.
Use the Apple TV's installed app list: after installing new apps, run Refresh Installed Apps.
When updating, keep the file name Papaya_AppleTV.c4z so Composer updates the driver in place.
Turn Debug Mode On only while troubleshooting. It turns itself off after 45 minutes.

Troubleshooting

Apple TV list is empty: the controller cannot see Bonjour from the Apple TV (different VLAN or multicast filtered). Type the IP into Apple TV IP Address.
No PIN appears on the TV: wake the Apple TV first. Check Allow Access is set to Everyone on the Same Network. Run Start Pairing again.
Pairing failed: MaxPeers: the Apple TV has too many paired remotes. Remove old ones under Settings > Remotes and Devices.
Status says "Run Start Pairing first, then enter the PIN": the PIN was typed without an active pairing. Run Start Pairing, then enter the new PIN.
Status: Offline: check the Apple TV has power and network. The driver re-probes every 30 seconds and searches by the Apple TV's own ID if the IP changed. Run Find Apple TVs, then Reconnect.
Status: Pair verify failed: the stored pairing no longer matches (for example the Apple TV was reset or the pairing deleted on the Apple TV). Run Forget Pairing, then Start Pairing.
Tile opens the app but the remote does nothing: check Tile Remote Keys names the room. Select the Apple TV, then the tile again. If it still fails, set After App Launch to Switch room to this Apple TV, and capture the Lua tab with Debug Mode On.
Wrong app opens, or Mini App Log says "no app named": run Refresh Installed Apps and List Connected Mini Apps. The app must be installed on this Apple TV. The Unknown App event fires in this case.
Link opens the app but not the title: that service is app-launch only on tvOS (Netflix, Hulu, Max and others), or the driver is older than 1.9.5. Check Driver Version.
"Open in (app)?" prompt on the TV: expected for Prime Video, Paramount+ and YouTube links. Turn on Auto-Press Open, or set Auto-Advance Speed to Slow if the press fires too early.
Tile in IR only mode only wakes the Apple TV: expected. Opening apps needs Control Mode IP or IP with IR backup.
Restart does nothing: Restart needs IR Output bound. Otherwise power-cycle the outlet.
Room Off does not sleep the Apple TV: check On Room Off is Sleep the Apple TV.
Anything else: set Debug Mode On, reproduce, and copy the Lua tab.

Limitations

No live typing or Siri voice from Control4. Use the iPhone/iPad Apple TV Remote for text.
No network restart. Restart works only over IR or by power-cycling the outlet.
Deep links depend on each streaming app. Netflix, Hulu and Max open the app only.
Wake-on-LAN works over Ethernet only, and some Apple TVs in deep sleep ignore it.
IR cannot open apps or read status.
Volume stays with the room's volume device (TV or receiver).
Some Apple TVs need a few seconds to wake before the first command is accepted. The driver retries once on a stale connection.

Version history highlights

1.9.15: driver code encrypted. No functional changes.
1.9.14: room-on from a Streaming Search launch selects the Apple TV again (reverted a navigator jump that picked the wrong source).
1.9.10 to 1.9.12: OPEN_LINK can turn the Apple TV's room on with the Apple TV as source (used by Streaming Search). Driver publishes its own room.
1.9.9: connection re-probes every 30 seconds, so the driver recovers on its own after the Apple TV wakes.
1.9.6: Auto-Press Open, Auto-Pick Profile and Auto-Advance Speed.
1.9.0 to 1.9.5: deep link overhaul, tested on hardware. Netflix and Hulu moved to app launch only.
1.8.0: removed the Apple TV Search keyboard tab (Control4 apps cannot type live).
1.7.0: renamed Apple TV by Papaya (file Papaya_AppleTV.c4z).
1.6.0: live power and play state, events, variables, skip and scan, Guide as app switcher, Wake-on-LAN, OPEN_LINK.
1.4.0: IR Output and Control Mode.
1.3.0: remote keys on app tiles.
1.2.0: discovery and following IP changes; wake before launch.
1.0.x: first release with Companion pairing, app launching and mini app hosting.