Skip to content

feat: Add wireless Apple TV devices to created tunnels - #2755

Merged
mykola-mokhnach merged 4 commits into
appium:masterfrom
mykola-mokhnach:tv-tun
Mar 14, 2026
Merged

feat: Add wireless Apple TV devices to created tunnels#2755
mykola-mokhnach merged 4 commits into
appium:masterfrom
mykola-mokhnach:tv-tun

Conversation

@mykola-mokhnach

@mykola-mokhnach mykola-mokhnach commented Mar 14, 2026

Copy link
Copy Markdown
Contributor

@mykola-mokhnach

Copy link
Copy Markdown
Contributor Author

@KazuCocoa Could you please test this update with your wireless AppleTV device? If everything works well I'll update related docs. The next step would be to try full e2e driver test with such device and a tunnel to make sure we don't have any gaps in the driver implementation.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adds Apple TV (tvOS) WiFi tunnel support to the existing tunnel-creation script so the tunnel registry can include both USB iOS devices and paired Apple TVs.

Changes:

  • Extend tunnel registry creation to merge USB tunnel results with Apple TV (WiFi) tunnel entries.
  • Add Apple TV tunnel setup/cleanup logic (packet stream server + resource teardown).
  • Update script reference docs to mention paired Apple TVs and linking to the pairing guide.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

File Description
scripts/tunnel-creation.mjs Adds Apple TV WiFi tunnel creation, merges results into a single registry, and expands cleanup to cover Apple TV resources.
docs/reference/scripts.md Updates the tunnel-creation script description to include paired Apple TVs and pairing guide reference.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

Comment thread scripts/tunnel-creation.mjs
Comment thread scripts/tunnel-creation.mjs Outdated
Comment thread scripts/tunnel-creation.mjs
Comment thread scripts/tunnel-creation.mjs Outdated
@KazuCocoa

KazuCocoa commented Mar 14, 2026

Copy link
Copy Markdown
Member

I assume getConnectedDevices needs to get the tunneled TV devicce in https://github.com/appium/appium-xcuitest-driver/blob/master/lib/device/real-device-management.ts#L254-L261 to make for apple tv work. So, current implementation doesn't work with WiFi only connected TVs while after start-appletv-tunnel is working.


This is logs I saw for the tunnel creation command itself - maybe good? I was confused appletv-id, but that was not this xcuitest driver level.

error - expected as no sudo:

info TunnelCreation Connecting to usbmuxd...
info TunnelCreation Listing all connected devices...
info TunnelCreation No USB devices found.
info TunnelCreation Starting Apple TV tunnel (WiFi)...
info BonjourDiscovery Starting Bonjour discovery
info BonjourDiscovery [ServiceResolver] Resolving service: C4FCDC34-D133-4876-AFE9-ECAC2E3DA12D
info BonjourDiscovery Stopping Bonjour discovery
info AppleTVTunnelService
info AppleTVTunnelService Discovered Apple TV devices:
info AppleTVTunnelService   1. Identifier: C4FCDC34-D133-4876-AFE9-ECAC2E3DA12D
info AppleTVTunnelService      Name: C4FCDC34-D133-4876-AFE9-ECAC2E3DA12D
info AppleTVTunnelService      IP: 192.168.5.1:49152
info AppleTVTunnelService      Model:
info AppleTVTunnelService      Version:
info AppleTVTunnelService ✅ Successfully verified with pair record: 130F723E-21CE-4060-9CE3-84B780BF3CE4
info AppleTVTunnelService 🔑 Using pair record: 130F723E-21CE-4060-9CE3-84B780BF3CE4
info AppleTVTunnelService 📱 Connected to device: C4FCDC34-D133-4876-AFE9-ECAC2E3DA12D (C4FCDC34-D133-4876-AFE9-ECAC2E3DA12D)
info AppleTVTunnelService    IP: 192.168.5.1:49152
info TunnelCreation Creating tunnel for Apple TV: C4FCDC34-D133-4876-AFE9-ECAC2E3DA12D
ERR! TunTap Error setting up TUN interface: Failed to connect to utun control socket: Operation not permitted
ERR! TunTap Error: Failed to connect to utun control socket: Operation not permitted
ERR! TunTap     at TunTap.open (file:///Users/kazu/github/appium-xcuitest-driver/node_modules/appium-ios-tuntap/lib/TunTap.js:67:43)
ERR! TunTap     at TunnelManager.setupInterface (file:///Users/kazu/github/appium-xcuitest-driver/node_modules/appium-ios-tuntap/lib/tunnel.js:114:27)
ERR! TunTap     at connectToTunnelLockdown (file:///Users/kazu/github/appium-xcuitest-driver/node_modules/appium-ios-tuntap/lib/tunnel.js:466:54)
ERR! TunTap     at process.processTicksAndRejections (node:internal/process/task_queues:105:5)
ERR! TunTap     at async TunnelManagerService.getTunnel (file:///Users/kazu/github/appium-xcuitest-driver/node_modules/appium-ios-remotexpc/build/src/lib/tunnel/index.js:85:24)
ERR! TunTap     at async TunnelCreator.setupAppleTVTunnels (file:///Users/kazu/github/appium-xcuitest-driver/scripts/tunnel-creation.mjs:315:16)
ERR! TunTap     at async main (file:///Users/kazu/github/appium-xcuitest-driver/scripts/tunnel-creation.mjs:529:28)
ERR! TunTap     at async file:///Users/kazu/github/appium-xcuitest-driver/scripts/tunnel-creation.mjs:563:1
ERR! TunTap  Failed to connect to tunnel:
WARN TunnelCreation Apple TV tunnel setup failed (ensure device is paired and on same network): Failed to connect to utun control socket: Operation not permitted
WARN TunnelCreation No tunnels created (no USB devices and no Apple TV tunnel).
WARN TunnelCreation Cleaning up tunnel resources...
info TunnelCreation Cleanup completed.
✔ tunnel-creation successfully ran
  • paired. 130F723E-21CE-4060-9CE3-84B780BF3CE4 came from paired record. S, I guess 66C99754-0446-4CDE-BB4B-5F0DC633A2E3 would be the uuid for the device...?
kazu $ sudo appium driver run xcuitest tunnel-creation
info TunnelCreation Connecting to usbmuxd...
info TunnelCreation Listing all connected devices...
info TunnelCreation No USB devices found.
info TunnelCreation Starting Apple TV tunnel (WiFi)...
info BonjourDiscovery Starting Bonjour discovery
info BonjourDiscovery [ServiceResolver] Resolving service: 66C99754-0446-4CDE-BB4B-5F0DC633A2E3
info BonjourDiscovery Stopping Bonjour discovery
info AppleTVTunnelService
info AppleTVTunnelService Discovered Apple TV devices:
info AppleTVTunnelService   1. Identifier: 66C99754-0446-4CDE-BB4B-5F0DC633A2E3
info AppleTVTunnelService      Name: 66C99754-0446-4CDE-BB4B-5F0DC633A2E3
info AppleTVTunnelService      IP: 192.168.5.1:49152
info AppleTVTunnelService      Model:
info AppleTVTunnelService      Version:
info AppleTVTunnelService ✅ Successfully verified with pair record: 130F723E-21CE-4060-9CE3-84B780BF3CE4
info AppleTVTunnelService 🔑 Using pair record: 130F723E-21CE-4060-9CE3-84B780BF3CE4
info AppleTVTunnelService 📱 Connected to device: 66C99754-0446-4CDE-BB4B-5F0DC633A2E3 (66C99754-0446-4CDE-BB4B-5F0DC633A2E3)
info AppleTVTunnelService    IP: 192.168.5.1:49152
info TunnelCreation Creating tunnel for Apple TV: 66C99754-0446-4CDE-BB4B-5F0DC633A2E3
info TunnelManager Creating new tunnel for address: fd53:4026:16b4::1
info PacketStreamServer Packet stream server listening on port 50000
info TunnelCreation Apple TV packet stream server started on port 50000
info TunnelCreation ✅ Apple TV tunnel ready for 66C99754-0446-4CDE-BB4B-5F0DC633A2E3
info TunnelRegistryServer Tunnel Registry Server started on port 42314
info TunnelRegistryServer API available at http://localhost:42314/remotexpc/tunnels
info TunnelCreation
info TunnelCreation === TUNNEL CREATION SUMMARY ===
info TunnelCreation USB tunnels: 0
info TunnelCreation Apple TV (WiFi) tunnels: 1
info TunnelCreation Total tunnels: 1
info TunnelCreation
info TunnelCreation 📁 Tunnel registry API:
info TunnelCreation    The tunnel registry is now available through the API at:
info TunnelCreation    http://localhost:42314/remotexpc/tunnels
info TunnelCreation
info TunnelCreation    Available endpoints:
info TunnelCreation    - GET /remotexpc/tunnels - List all tunnels
info TunnelCreation    - GET /remotexpc/tunnels/:udid - Get tunnel by UDID
info TunnelCreation    - GET /remotexpc/tunnels/metadata - Get registry metadata
info TunnelCreation    curl http://localhost:42314/remotexpc/tunnels/66C99754-0446-4CDE-BB4B-5F0DC633A2E3
WARN TunnelCreation Cleaning up tunnel resources...
info TunnelCreation Closing 1 Apple TV tunnel(s)...
info TunnelCreation Closed Apple TV tunnel for 66C99754-0446-4CDE-BB4B-5F0DC633A2E3
info TunnelCreation Cleanup completed.
  • what value was expected as appletv-device-id? I expected paired record 130F723E-21CE-4060-9CE3-84B780BF3CE4 or 66C99754-0446-4CDE-BB4B-5F0DC633A2E3. But looks like the TV was treated as 157C5D7A-0FB2-403B-9F62-BB59187DCE92. Where the 157C5D7A-0FB2-403B-9F62-BB59187DCE92 came from??
kazu $ sudo appium driver run xcuitest tunnel-creation --appletv-device-id=130F723E-21CE-4060-9CE3-84B780BF3CE4
info TunnelCreation Connecting to usbmuxd...
info TunnelCreation Listing all connected devices...
info TunnelCreation No USB devices found.
info TunnelCreation Starting Apple TV tunnel (WiFi)...
info BonjourDiscovery Starting Bonjour discovery
info BonjourDiscovery [ServiceResolver] Resolving service: 157C5D7A-0FB2-403B-9F62-BB59187DCE92
info BonjourDiscovery Stopping Bonjour discovery
info AppleTVTunnelService
info AppleTVTunnelService Discovered Apple TV devices:
info AppleTVTunnelService   1. Identifier: 157C5D7A-0FB2-403B-9F62-BB59187DCE92
info AppleTVTunnelService      Name: 157C5D7A-0FB2-403B-9F62-BB59187DCE92
info AppleTVTunnelService      IP: 192.168.5.1:49152
info AppleTVTunnelService      Model:
info AppleTVTunnelService      Version:
ERR! AppleTVTunnelService
ERR! AppleTVTunnelService Device with identifier 130F723E-21CE-4060-9CE3-84B780BF3CE4 not found in discovered devices.
ERR! AppleTVTunnelService Available devices:
ERR! AppleTVTunnelService   - 157C5D7A-0FB2-403B-9F62-BB59187DCE92 (157C5D7A-0FB2-403B-9F62-BB59187DCE92)
WARN TunnelCreation Apple TV tunnel setup failed (ensure device is paired and on same network): Device with identifier 130F723E-21CE-4060-9CE3-84B780BF3CE4 not found. Please check available devices above.
WARN TunnelCreation No tunnels created (no USB devices and no Apple TV tunnel).
WARN TunnelCreation Cleaning up tunnel resources...
info TunnelCreation Cleanup completed.
✔ tunnel-creation successfully ran
  • With 157C5D7A-0FB2-403B-9F62-BB59187DCE92
kazu $ sudo appium driver run xcuitest tunnel-creation --appletv-device-id=157C5D7A-0FB2-403B-9F62-BB59187DCE92
info TunnelCreation Connecting to usbmuxd...
info TunnelCreation Listing all connected devices...
info TunnelCreation No USB devices found.
info TunnelCreation Starting Apple TV tunnel (WiFi)...
info BonjourDiscovery Starting Bonjour discovery
info BonjourDiscovery [ServiceResolver] Resolving service: 157C5D7A-0FB2-403B-9F62-BB59187DCE92
info BonjourDiscovery Stopping Bonjour discovery
info AppleTVTunnelService
info AppleTVTunnelService Discovered Apple TV devices:
info AppleTVTunnelService   1. Identifier: 157C5D7A-0FB2-403B-9F62-BB59187DCE92
info AppleTVTunnelService      Name: 157C5D7A-0FB2-403B-9F62-BB59187DCE92
info AppleTVTunnelService      IP: 192.168.5.1:49152
info AppleTVTunnelService      Model:
info AppleTVTunnelService      Version:
info AppleTVTunnelService
info AppleTVTunnelService Filtered to specific device: 157C5D7A-0FB2-403B-9F62-BB59187DCE92
info AppleTVTunnelService ✅ Successfully verified with pair record: 130F723E-21CE-4060-9CE3-84B780BF3CE4
info AppleTVTunnelService 🔑 Using pair record: 130F723E-21CE-4060-9CE3-84B780BF3CE4
info AppleTVTunnelService 📱 Connected to device: 157C5D7A-0FB2-403B-9F62-BB59187DCE92 (157C5D7A-0FB2-403B-9F62-BB59187DCE92)
info AppleTVTunnelService    IP: 192.168.5.1:49152
info TunnelCreation Creating tunnel for Apple TV: 157C5D7A-0FB2-403B-9F62-BB59187DCE92
info TunnelManager Creating new tunnel for address: fd3d:9dfc:2780::1
info PacketStreamServer Packet stream server listening on port 50000
info TunnelCreation Apple TV packet stream server started on port 50000
info TunnelCreation ✅ Apple TV tunnel ready for 157C5D7A-0FB2-403B-9F62-BB59187DCE92
info TunnelRegistryServer Tunnel Registry Server started on port 42314
info TunnelRegistryServer API available at http://localhost:42314/remotexpc/tunnels
info TunnelCreation
info TunnelCreation === TUNNEL CREATION SUMMARY ===
info TunnelCreation USB tunnels: 0
info TunnelCreation Apple TV (WiFi) tunnels: 1
info TunnelCreation Total tunnels: 1
info TunnelCreation
info TunnelCreation 📁 Tunnel registry API:
info TunnelCreation    The tunnel registry is now available through the API at:
info TunnelCreation    http://localhost:42314/remotexpc/tunnels
info TunnelCreation
info TunnelCreation    Available endpoints:
info TunnelCreation    - GET /remotexpc/tunnels - List all tunnels
info TunnelCreation    - GET /remotexpc/tunnels/:udid - Get tunnel by UDID
info TunnelCreation    - GET /remotexpc/tunnels/metadata - Get registry metadata
info TunnelCreation    curl http://localhost:42314/remotexpc/tunnels/157C5D7A-0FB2-403B-9F62-BB59187DCE92
WARN TunnelCreation Cleaning up tunnel resources...
info TunnelCreation Closing 1 Apple TV tunnel(s)...
info TunnelCreation Closed Apple TV tunnel for 157C5D7A-0FB2-403B-9F62-BB59187DCE92
info TunnelCreation Cleanup completed.

So, this script itself is ok, but still I need to learn the tools' behavior.
One of them are different from udid nor identifier available via devicectl list devices command. The identifier would differ from the pairing info. Could they change every connection...?

I also ran the https://github.com/appium/appium-ios-remotexpc a bit. Then, the start-appletv-tunnel had:

info WiFiTunnel ✅ Apple TV tunnel is ready!
info WiFiTunnel Use: --rsd fd40:2ba:de4c::1 55695
info WiFiTunnel

like this log as well. Not sure what this means, but it let me think Apple TV would need to run start-tunnel and start-appletv-tunnel - both at once?

cc @navin772

log.info('\n Available endpoints:');
log.info(' - GET /remotexpc/tunnels - List all tunnels');
log.info(' - GET /remotexpc/tunnels/:udid - Get tunnel by UDID');
log.info(' - GET /remotexpc/tunnels/metadata - Get registry metadata');

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks like this endpoint is wrong. I'll create a removal PR to the repo

@mykola-mokhnach

Copy link
Copy Markdown
Contributor Author

@KazuCocoa I assume we need also to update the logic responsible for listing devices in xcuitest driver. Currently it relies on the legacy ios-device lib instead of the remotexpc one. I assume tunnels are ok, we just need now to update the driver flow

@KazuCocoa

Copy link
Copy Markdown
Member

Yes, it will need to be updated. This apple tv behavior is kind of WiFi only connected one specific one so not necessary to remove the legacy one - which is for USB connected devices

@KazuCocoa KazuCocoa left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The command itself worked. I don't have much knowledge about the new lib's behavior, so still XCUITest session doesn't work for WiFi only connected ones but this PR itself lgtm

@mykola-mokhnach

Copy link
Copy Markdown
Contributor Author

@KazuCocoa I have created appium/appium-ios-remotexpc#158 and will try to wire it up into xcuitest driver device selection as soon as it's merged. Will need some help with testing it later

@mykola-mokhnach
mykola-mokhnach merged commit 07911a7 into appium:master Mar 14, 2026
7 of 15 checks passed
@mykola-mokhnach
mykola-mokhnach deleted the tv-tun branch March 14, 2026 20:11
github-actions Bot pushed a commit that referenced this pull request Mar 14, 2026
## [10.30.0](v10.29.0...v10.30.0) (2026-03-14)

### Features

* Add wireless Apple TV  devices to created tunnels ([#2755](#2755)) ([07911a7](07911a7))
@github-actions

Copy link
Copy Markdown
Contributor

🎉 This PR is included in version 10.30.0 🎉

The release is available on:

Your semantic-release bot 📦🚀

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants