CrestronHomeDriver.Apple.AppleTV 1.5.1

dotnet add package CrestronHomeDriver.Apple.AppleTV --version 1.5.1
                    
NuGet\Install-Package CrestronHomeDriver.Apple.AppleTV -Version 1.5.1
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="CrestronHomeDriver.Apple.AppleTV" Version="1.5.1" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="CrestronHomeDriver.Apple.AppleTV" Version="1.5.1" />
                    
Directory.Packages.props
<PackageReference Include="CrestronHomeDriver.Apple.AppleTV" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add CrestronHomeDriver.Apple.AppleTV --version 1.5.1
                    
#r "nuget: CrestronHomeDriver.Apple.AppleTV, 1.5.1"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package CrestronHomeDriver.Apple.AppleTV@1.5.1
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=CrestronHomeDriver.Apple.AppleTV&version=1.5.1
                    
Install as a Cake Addin
#tool nuget:?package=CrestronHomeDriver.Apple.AppleTV&version=1.5.1
                    
Install as a Cake Tool

AppleTVCrestronDriver

Current GitHub/NuGet release: 1.5.1

Download 1.5.1 or use the matching NuGet driver distribution. This patch includes the audited dependency and lifecycle corrections; see release notes. Existing configuration and pairing formats are retained. Crestron catalog/submission versions below retain their separate attribution.

Both Apple TV drivers use 1.5.1. Updating the existing V1 Video Server requires a full processor reboot.

Version 1.5.0 introduced programmable app-launch commands to the companion extension, with confirmed wake handling and a two-step Route AppleTV → Launch app Quick Action setup. The Video Server retains its existing pairing, connection and routing behavior. See the extension setup guide.

See the changelog and release notes. Test, CI and build history is recorded separately in development and validation history.

A Crestron Home Video Server driver that controls an Apple TV over its Companion Link protocol, providing pairing, connection status, and remote-control (arrow keys, select, menu, home, play/pause, power) directly from the Crestron Home app.

Trademark notice and disclaimer: Apple, Apple TV, and tvOS are trademarks of Apple Inc., registered in the U.S. and other countries. This project is an independent, unofficial driver and is not affiliated with, endorsed by, sponsored by, or approved by Apple Inc. in any way. "Apple TV" and other Apple product names are used solely to describe compatibility and interoperability. No Apple software, assets, or confidential documentation are included in or derived for this repository. Crestron and Crestron Home are trademarks or registered trademarks of Crestron Electronics, Inc. This project is not affiliated with, endorsed by, or sponsored by Crestron Electronics, Inc.

License: MIT + Commons Clause


Two packages, one repository: This repository hosts two separately installable Crestron Home drivers that are released together under the same version tag: this Video Server driver (CrestronHomeDriver.Apple.AppleTV), documented below, and a companion Extension driver (CrestronHomeDriver.Apple.AppleTVExtension) that adds an app-selection and remote-control UI on top of it. Because GitHub only renders one root README, see AppleTVCrestronExtensionDriver/README.md for the Extension driver's own installation, configuration, and changelog.


Driver Architecture

This driver is a Crestron Home Video Server driver, implemented on the Crestron RAD ABasicVideoServer model. It connects to a single Apple TV over the Companion Link protocol using the AppleTVControlLibrary NuGet package for pairing, session, and remote-control functionality, and its companion AppleTVControlLibrary.Discovery package for locating the Apple TV on the network by name.

The driver only implements Companion Link (the protocol tvOS remotes and the Apple TV Remote app use for HID input, media transport, volume, and power state). It does not implement MRP, AirPlay 2, RAOP, or DMAP/DACP.


Features

  • Pairing directly from the Crestron Home configuration UI: enter the Apple TV's name, start pairing, and enter the on-screen PIN when prompted
  • Persisted pairing credentials so the Apple TV does not need to be re-paired after a processor reboot or driver reinitialization
  • Automatic reconnection and online/offline status reporting
  • Arrow key navigation, Select, Menu, Home, Back
  • Discrete power on/off
  • Play/Pause transport control

Usage

Pairing

  1. Add a new device in Crestron Home. Search for Apple TV Companion in the driver list — Crestron Home lists hundreds of Apple TV drivers, so search by that exact base model name (not just "Apple TV") to find this one.
  2. Enter the Apple TV Name exactly as it appears under Settings > Remotes and Devices on the Apple TV (this name is used to locate it via Companion Link discovery).
  3. Turn on Pair Now. A pairing code will appear on the Apple TV screen.
  4. Enter that four-digit code into the Pairing PIN field to complete pairing.

Once paired, the driver reconnects automatically on subsequent processor reboots without repeating this flow.

Video routing reminder: This driver only handles Companion Link control (pairing, remote input, and power/connection status) — it does not perform any HDMI switching or display control. After adding the driver, make sure you also configure the Apple TV's video routing to a display or switcher device (for example, an HDMI input assignment on a matrix switcher, or a display's source binding) in Crestron Home so that selecting the Apple TV actually switches the display to the correct input.

App Quick Actions

The companion extension exposes a separate Launch <app name> command for each installed Apple TV app. Create a Quick Action in Sequence mode with two steps: route the Video Server's Apple TV source to the target room, then run the extension's app command. The extension handles a required wake internally; no separate Home command is needed. See the complete Setup and Configure Pro instructions.

Keep both drivers installed. The Video Server owns the saved pairing, Companion Link session and native routable source used by Home and TSR-310. The extension supplies its richer control UI and programmable app commands. This release does not hide either driver's UI or change source visibility.

Known Issues

  • Configure Pro shows stale attribute descriptions. The driver updates the Apple TV Name, Pair Now, and Pairing PIN descriptions live to reflect current pairing/connection status. The Crestron Home Setup app reflects these updates correctly and immediately. The Configure Pro app, however, can display an outdated or default description after reopening a device's configuration page, even though the driver already sent the correct, current description. This appears to be a Configure Pro caching/refresh issue rather than a driver defect; use the Setup app if you need to confirm the current pairing status text.

Installation

Updating an existing installation

Update both the Apple TV Companion Video Server driver and the Apple TV Companion Media extension from the same release. The Video Server uses the V1 SDK and requires a full processor reboot to load an updated assembly. The Entity V2 extension supports an in-place driver update.

Retain the existing devices and their configuration. The Video Server reuses its saved pairing after the reboot. IP addresses and Companion Link ports are cached endpoints. If the cache fails, the driver discovers the saved Apple TV identity through mDNS, connects using the existing pairing, and saves the working endpoint in its driver settings.

Allow the Apple TV to finish sleeping before turning it back on. In live testing, an immediate off/on sequence left it asleep; allowing five seconds after confirmed sleep worked. That interval is an observed test result, not a minimum timing guarantee.

The best way to download and install this driver on a Crestron Home system is to use the Crestron Home Driver Feed Installer repository and application.

If you prefer to install manually, use the attached .pkg asset from the relevant GitHub Release. The automatic GitHub Source code (zip) and Source code (tar.gz) assets are repository snapshots, not installable Crestron driver packages.

NuGet package availability: this driver is also published as the CrestronHomeDriver.Apple.AppleTV NuGet package. This NuGet package conforms to the Crestron Home Driver NuGet Publishing Standard v1. It is a distribution wrapper for the final .pkg artifact, includes the required crestron-driver-package.json manifest, and is not intended as a direct DLL reference package.

Crestron Home Driver NuGet Publishing Standard v1 is not an official Crestron product or specification. It is an open source packaging standard created to facilitate community distribution and discovery of Crestron Home drivers through NuGet.

  1. Download the generated .pkg asset from the GitHub Release, or build it yourself using the instructions in Building from Source.
  2. Upload the .pkg file to your Crestron Home processor manually (for example via SFTP to /user/ThirdPartyDrivers/Import).
  3. In the Crestron Home configuration UI, add a new device and select the Apple TV Companion driver (search by that exact name, since Crestron Home lists hundreds of Apple TV drivers).
  4. Configure the driver as described in Pairing above.

Building from Source

Dependencies

Build

dotnet build AppleTVCrestronDriver.slnx -c Release

The build pipeline:

  1. Compiles the driver targeting net472
  2. Bumps DriverVersion and VersionDate in AppleTVCrestronDriver.json
  3. ILRepacks runtime dependencies into the driver assembly
  4. Runs PatchMergedAssembly.ps1 against the merged assembly
  5. Packages the driver into a .pkg using Crestron's ManifestUtil

GitHub Release Asset

This repository includes a GitHub Actions workflow that builds the Release package and attaches the generated .pkg to a GitHub Release.

The same release workflow builds and publishes both packages together from this repository: this driver's CrestronHomeDriver.Apple.AppleTV NuGet package and the companion Extension driver's CrestronHomeDriver.Apple.AppleTVExtension NuGet package, each wrapping its own generated .pkg artifact. The workflow validates that both driver manifests share the same major.minor.release version before building, since the two are released as a single interlocked release.

Typical release flow:

  1. Push the release commit and tag (after confirming both driver manifests' DriverVersion major.minor.release match)
  2. Publish the GitHub Release for that tag
  3. Let the workflow build and attach both .pkg assets, and publish both NuGet packages, automatically

Testing

AppleTVCrestronDriver.Tests is a NUnit unit/integration test project with 149 logic tests covering the driver logic that does not require a live Crestron control system or a physical Apple TV. Driver orchestration logic (pairing, stored-device persistence, connection/reconnect handling, and related state) has been extracted behind small internal interfaces so it can be exercised directly by this suite. Coverage includes:

  • Pairing state helpers and stored credential persistence
  • The Companion Link pairing handshake, driven end-to-end against the in-repo fake device/host
  • Bridge protocol command/event tokenization and Base64 text encode/decode round-trips (AppleTvBridgeProtocol)
  • The extracted keyboard focus/text relay bridge (AppleTvKeyboardBridge), including on-screen keyboard show/hide and live text forwarding, without needing to construct the full Crestron RAD base-driver chain

It is not a publishable artifact (IsPackable/IsPublishable are both false) and is not part of the release .pkg/NuGet package built above -- it exists purely to validate the driver source in this repository during development.

Running the tests

dotnet test AppleTVCrestronDriver.Tests/AppleTVCrestronDriver.Tests.csproj -c Debug

Visual Studio Test Explorer uses the NUnit adapter. Tests target net472, use a fresh fixture instance for each test, and run serially to preserve the existing test isolation. Test project builds merge the driver dependencies but skip production driver version bumps, packaging and deployment.

Running the same suite on Crestron Home

The solution also includes AppleTVCrestronDriver.ProcessorTests. Build that project in Debug in Visual Studio to create and deploy the standalone AppleTVCrestronDriver Tests package, using private local deployment settings. Find it in the Utility category in Crestron Home Configure. Run its 149 logic tests and 15 processor lifecycle tests from its tile or discover the package in the Windows NUnit runner. This suite uses simulated Apple TV services and loopback connections; it needs no Apple TV pairing credentials or live-test settings.

The test package has its own identity and test tile. The production drivers' UIs are not installed by it. Its .pkg is a separate development artifact, not a NuGet package and not part of the production driver release workflow. Processor packaging also requires a sibling CrestronHomeNUnit checkout.

Dependency on AppleTVControlLibrary source

The test project references the in-repo AppleTVControlLibrary FakeDevice test helpers (FakeCompanionDevice/FakeCompanionTcpHost) to drive real pairing-handshake integration tests without sockets to actual hardware. This requires the AppleTVControlLibrary repository to be cloned as a sibling directory of this repository (i.e. ../AppleTVControlLibrary relative to this repository's root), matching the relative paths already used by AppleTVCrestronDriver.slnx for the non-built AppleTV.Companion/AppleTV.Companion.Discovery source projects.


Repository Notes

  • XML documentation generation is enabled in the project build
  • The release workflow builds on windows-latest, or wraps reviewed SHA-256-pinned packages without rebuilding them. NuGet publishing uses GitHub OIDC Trusted Publishing
  • The repository includes the driver package/build scripts needed for packaging and deployment
  • The Extension driver project links several source files directly from this project (shared credential-lookup and bridge client code) rather than using a ProjectReference, so it cannot be built or extracted into a separate repository independently of this one

License

MIT + Commons Clause © 2026 Neil Colvin — see LICENSE.

Free to use and modify. You may not sell the Software as a standalone product or sublicense it. Commercial system integration work (for example, a Crestron installer commissioning a customer system) is explicitly permitted, even where a fee is charged for that service.

Apple and Apple TV are trademarks of Apple Inc.

Note: This project references Crestron.DeviceDrivers.DevKit, which is subject to Crestron's SDK license agreement. That license governs the SDK libraries only; the source code in this repository is licensed independently under the terms above.

Expanded driver behavior tests

Cover saved pairing, shared credential restoration, discovery identity persistence, configured-name changes, retry recovery and superseded discovery/connection attempts. Cancellation prevents old connection attempts from persisting identity or reporting a paired state for a newer configuration.

Real extension entities publish bridge events, maintain connection and tile state, clear keyboard text when focus is lost, reject missing device names before storage access, and clear device-specific UI state when configuration is removed.

The current source builds a package with 149 offline tests and 15 SDK entity/lifecycle tests. The linked 1.1.0 release assets retain their original test inventory. The processor package remains net472 only, appears under Utility in Configure, and can run independently through its own tile or the Windows NUnit runner. These fixtures use synthetic data and do not operate installed devices or authenticate with real accounts.

AppleTVCrestronDriver.Lifecycle.Tests runs the entity checks against the real desktop SDK on .NET 10. It compiles the relevant driver sources and shares fixture sources with the net472 processor tests. Building this project does not deploy a driver. A locally supplied Newtonsoft.Json.Compact.dll is needed by the SDK's manifest reader; it is supplied by the processor at runtime and must not be added to source control or bundled with the processor test package.

dotnet test AppleTVCrestronDriver.Tests/AppleTVCrestronDriver.Tests.csproj --filter "TestCategory!=Processor"
dotnet test AppleTVCrestronDriver.Lifecycle.Tests/AppleTVCrestronDriver.Lifecycle.Tests.csproj

Desktop success does not establish Mono compatibility. Build the processor test project in Visual Studio, deploy it, and run both suites on the processor. The fixtures cover configuration, restoration, refresh/reconnect races and disposal using simulated responses. Real installed-driver health and optional live-device checks remain separate from these repeatable suites.

Driver build and release versions

The driver's JSON manifest is the source of its four-component build version. Debug builds increment only the fourth component; for example, 2.0.001.0005 becomes 2.0.001.0006. MSBuild's Version and default PackageVersion are derived from that same manifest and refreshed after the increment; their numeric form is 2.0.1.6. Assembly binding versions remain separate. Test-only references and IDE design-time builds do not increment the production driver version.

GitHub tags and NuGet releases retain three components: v2.0.1 and 2.0.1. Prepare the manifest's first three components for the intended release before tagging. Release CI checks that the tag matches, resets the fourth component to zero, and verifies the generated .pkg version against the manifest and release version before publishing. It does not increment the selected patch again. Local Release builds preserve the manifest. A later Debug build can legitimately be newer than a published release; the processor test package has its own independent version.

Deployment validation compares the exact built .pkg against the imported catalogue entry and installed instance, numerically including all four components. Upload/import alone does not activate the new version. Keep the tested package and its hash: rebuilding creates a new artifact that must be validated again.

Run pwsh -File tools/Test-DriverVersioning.ps1 to check these rules with temporary manifests; this does not change the working driver manifest or deploy anything.

See versioning details for build, release and installed-instance verification rules.

For automated local tests, processor tests and gated driver deployment, see the Crestron Home NUnit CI development guide. It covers private configuration, live-test gates, install/update waits, results and optional test-package removal.

Visual Studio processor workflow

The solution includes AppleTVCrestronDriver.WorkflowTests, using the published Crestron Home Test Adapter. It exposes the complete gated workflow in Test Explorer while the ordinary NUnit fixtures remain available for local testing. Configure its private settings before execution; hosted CI verifies discovery without accessing hardware.

Publishing when local hardware is unavailable

The publish/release workflows support an explicit manual override when the processor or local self-hosted GitHub Actions runner is unavailable. Select skip_hardware_checks and provide a single-line hardware_skip_reason. Use the workflow's normal source and version controls. The override applies only to that invocation and is recorded with the exact source revision in its warning and job summary; it does not create a passing hardware-test result.

GitHub-hosted validation remains mandatory for the checked-out source, and the normal build, tests and packaging steps still run. Wait for the configured hosted workflows to pass, or run them on the same source revision first. None of these hosted checks needs the local runner or processor. Automatic tag/release-triggered runs retain the normal hardware checks; use a manual invocation of the updated release workflow when an offline override is needed. See test dependencies and validation instructions for both drivers.

NUnit 5 test tooling

All maintained NUnit suites use the official NUnit 5.0.0 framework. Async exception assertions are awaited, and discarded-task warnings fail test builds. Processor test packages use CrestronHomeNUnit SDK 2.2.0; workflow and Android suites, where provided, use the released 2.2.0 adapter. Tests remain available in Visual Studio, VS Code and the command line. Live and manual tests still require their documented devices and permissions. This is a test-tooling update; the published product version and runtime behavior are unchanged.

NUnit 5 test package

Test package 1.1.0 uses NUnit 5.0.0. It is independent of the product version. Download package, documentation, validation, exact source revisions, and SHA-256 checksums are attached to the existing product release. No product binary or NuGet version changed for this test update.

Validated on 1 October 2026: 108 offline cases passed in each of two runs from the packaged assembly on Windows. Processor-only lifecycle fixtures are skipped on Windows and are not included in that pass count. All suite identities were checked against source discovery. Live/manual tests and execution on the processor were not repeated during this migration; earlier hardware results do not certify this new package.

There are no supported framework assets in this package.

Learn more about Target Frameworks and .NET Standard.

This package has no dependencies.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
1.5.1 98 11/10/2026
1.5.0 111 11/7/2026
1.4.5 103 11/7/2026
1.4.4 189 9/22/2026
1.4.3 175 9/13/2026
1.4.1 229 8/18/2026
1.4.0 215 8/18/2026
1.3.3 229 8/16/2026
1.3.2 223 8/16/2026
1.3.1 210 8/13/2026
1.3.0 227 8/13/2026
1.1.2 228 8/11/2026
1.1.1 233 8/10/2026
1.1.0 229 8/9/2026

# AppleTVCrestronDriver 1.5.1

This patch corrects the dependency and lifecycle issues described below.

- Use AppleTVControlLibrary and Discovery 2.2.8.
- Keep queued Video Server commands tied to the session that accepted them. Drop retired commands and drain held-key release and session shutdown before replacement.
- Preserve the existing V1/V2 bridge, pairing files, source routing and Quick Action configuration.

## Installation

Use the driver package from [GitHub](https://github.com/oznetmaster/AppleTVCrestronDriver/releases/tag/v1.5.1) or the matching NuGet distribution. Import the package, then update the existing driver in Home Setup or Configure Pro. Importing alone does not update the running instance. Existing pairing and configuration formats are retained; removal and re-add is not a routine update step.

Both the V1 Video Server and V2 companion are released together as 1.5.1. Updating an existing V1 driver requires a full processor reboot; the V2 companion does not require a reboot. Preserve the existing pairing files. Quick Actions keep the two-step Route AppleTV -> Launch app setup.

## Validation

Passed 167 workstation Debug and 167 Release test executions, plus 167 native net472/Mono processor tests. Processor validation used fake transports and synthetic credentials; no new physical-device acceptance or endurance run is claimed. Existing processor configuration and all pairing files were preserved. See [development history](DEVELOPMENT-HISTORY.md) for provenance and limits.

This GitHub/NuGet release does not replace any submitted Crestron package. Submission-specific PDFs and correspondence are excluded from public artifacts.