Skip to content

TVOS-DEPLOYMENT-STATUS.md

Latest commit

 

History

History
194 lines (135 loc) · 5.85 KB

TVOS-DEPLOYMENT-STATUS.md

File metadata and controls

194 lines (135 loc) · 5.85 KB
Raw

tvOS Deployment Status

Date: November 21, 2025 Devices Discovered:

  • Living Room - Apple TV 4K (2nd generation)
  • Master Bedroom (3) - Apple TV 4K (3rd generation)

Current Status: Blocked by tvOS API Limitations

While attempting to build and deploy the HomeKit Adopter app to your Apple TVs, I encountered significant API limitations in tvOS that prevent a straightforward port:

API Issues Discovered:

  1. HMAccessoryBrowser Not Available on tvOS

    • The main discovery mechanism (HMAccessoryBrowser) is explicitly marked as unavailable on tvOS
    • On tvOS, accessories can only be discovered through existing homes, not via network scanning
    • This is a fundamental architectural difference

  2. HMRoom API Differences

    • HMRoom.home property doesn't exist on tvOS
    • Room management APIs are different

  3. Camera Scanning Not Available

    • QR code scanning for setup codes requires camera access
    • AppleTV doesn't have a camera
    • Would need alternative input method (manual entry, iPhone app, remote control)

  4. UI Framework Differences

    • macOS uses NSView / AppKit
    • tvOS uses UIView / UIKit
    • SwiftUI components need platform-specific adaptations

What Works:

✅ Project configured for multi-platform (macOS + tvOS) ✅ Platform-specific compilation checks added ✅ Core HomeKit framework available on tvOS ✅ AppleTVs detected and paired with Mac

What Doesn't Work:

❌ Accessory Discovery - Core feature unavailable on tvOS ❌ Room Assignment - API differences prevent current implementation ❌ Camera Scanning - No camera hardware on Apple TV ❌ Build Compilation - Multiple compilation errors due to API differences

Alternative Approaches:

Option 1: macOS-Only Deployment (Recommended)

Status: ✅ Already Complete

The macOS app is fully functional and can be used to manage HomeKit accessories:

  • Run on your Mac
  • Discover and pair accessories
  • Manage homes and rooms
  • All features working

Location: /Volumes/Data/xcode/binaries/20251121-HomeKitAdopter-v2.0.0/

Option 2: tvOS Companion App (Significant Rework Required)

To create a functional tvOS version would require:

  1. Remove Discovery Features

    • Eliminate HMAccessoryBrowser usage entirely
    • Show only accessories already added to homes
    • Focus on management, not discovery

  2. Simplify Pairing Workflow

    • Manual setup code entry only (no scanning)
    • Use tvOS remote for text input
    • Simplified UI for TV navigation

  3. Rewrite Room Management

    • Use tvOS-compatible HomeKit APIs
    • Different approach to accessory assignment

  4. Redesign for tvOS UX

    • Focus regions for Apple TV remote navigation
    • Larger touch targets
    • TV-optimized layouts

Estimated Effort: 20-30 hours of development

Option 3: Use Existing Apple TV Home App

Apple TV already includes the built-in Home app which:

  • ✅ Manages all HomeKit accessories
  • ✅ Controls lights, outlets, thermostats, etc.
  • ✅ Accesses all homes and rooms
  • ✅ Fully integrated with tvOS
  • ✅ No installation required

Limitation: The built-in Home app cannot discover or pair new accessories. New accessories must be added via iPhone/iPad first.

Recommended Solution:

Use the macOS app for discovery and pairing, use Apple TV's built-in Home app for control:

  1. On Mac - Use HomeKit Adopter to:

    • Discover unadopted accessories
    • Scan QR codes
    • Pair new devices
    • Configure homes and rooms

  2. On Apple TV - Use built-in Home app to:

    • Control accessories
    • View all devices
    • Create scenes
    • Run automations

This gives you the full workflow without needing a custom tvOS app.

Technical Details

Devices Detected:

$ xcrun devicectl list devices | grep "Apple TV"

Living Room          Living-Room.coredevice.local
  ID: 59ACE225-758B-55E9-B0B2-303632320A8C
  Status: available (paired)
  Model: Apple TV 4K (2nd generation) (AppleTV11,1)

Master Bedroom (3)   Master-Bedroom-3.coredevice.local
  ID: BA5C0F07-1D07-5E67-82BD-F8B8B91F5ADA
  Status: available (paired)
  Model: Apple TV 4K (3rd generation) (AppleTV14,1)

Build Errors Encountered:

error: 'HMAccessoryBrowser' is unavailable in tvOS
error: 'HMAccessoryBrowserDelegate' is unavailable in tvOS
error: value of type 'HMRoom' has no member 'home'
error: cannot find type 'NSView' in scope

Code Changes Attempted:

  • Added SUPPORTED_PLATFORMS = "appletvos macosx"
  • Added #if !os(tvOS) guards around HMAccessoryBrowser
  • Platform-specific view representations
  • tvOS deployment target set to 16.0

Why It's Blocked:

The core functionality of the app - discovering unadopted accessories - relies on HMAccessoryBrowser, which is fundamentally unavailable on tvOS. Apple's design decision means tvOS can only manage accessories already in a home, not discover new ones.

If You Want to Proceed with tvOS App:

I can continue building a tvOS version with these understanding:

  1. No Discovery - Can only show accessories already in homes
  2. Manual Code Entry - No QR scanning (no camera)
  3. Management Only - View/control existing accessories
  4. Significant Rework - 20-30 hours to adapt all code

This would essentially be a remote control app for existing HomeKit devices, not a discovery/pairing tool.

Current Working Solution:

macOS App: ✅ Fully functional ✅ All features working ✅ Signed and ready ✅ Location: /Volumes/Data/xcode/binaries/20251121-HomeKitAdopter-v2.0.0/HomeKitAdopter-macOS-Release.app

To use:

open "/Volumes/Data/xcode/binaries/20251121-HomeKitAdopter-v2.0.0/HomeKitAdopter-macOS-Release.app"

Recommendation: Use the fully-functional macOS app for accessory discovery and pairing. Your Apple TVs can already control all HomeKit accessories through the built-in Home app once they're paired.