Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift

VM window: the Apple Watch side button

Maximilian Paß95809001d323
diff --git a/Research/0_binary_patch_comparison.md b/Research/0_binary_patch_comparison.md
index 1f2b12fd..ffe8e08d 100644
--- a/Research/0_binary_patch_comparison.md
+++ b/Research/0_binary_patch_comparison.md
@@ -3524,7 +3524,16 @@ tvOS installer does; all its imports are in the watchOS 26.4 arm64e cache.
`filesystem-boot-launchd_cache_loader_unsecure_cache_gate` thins the universal
binary to its arm64e slice first (`MachOFatSlice`). vphoned is the arm64 daemon
marked watchOS (`vphoned-watchos`); its HID presses reach the crown as Home
-(consumer 0x40) and the side button as Power (0x30).
+(consumer 0x40). The side button is consumer Help (0x0C/0x95), not Power:
+N227b's `/buttons` node names two buttons, `help` and `menu`, and Carousel's
+`-[CSLHIDEventStreamWriter _eventForUsagePage:usage:down:]` maps 0x0C/0x40 to
+the crown, 0x0C/0x95 to the side button (to the Action button only when
+`shouldSimulateSting`) and vendor 0xFF01/0x200 to the Action button, which a
+Series 11 lacks. `-[CSLUIHIDHandler init]` reads consumer Power (0x30) as the
+separate `power` mask, which only sleeps or wakes the display. The VM window's
+Device › Side Button (watch guests only) and the host automation key `side`
+send 0x95; on 2026-10-20 it woke the `pair-watch` guest and opened Control
+Center from the watch face, where 0x30 turned the display off.
vphoned links Vision (IcliKit's OCR) weakly: watchOS ships no Vision, and dyld
refused the daemon. Every other library it links strongly, and every symbol it
diff --git a/Skills/vphone-guest-control/references/guest-socket.md b/Skills/vphone-guest-control/references/guest-socket.md
index 2241698b..d5ff53d9 100644
--- a/Skills/vphone-guest-control/references/guest-socket.md
+++ b/Skills/vphone-guest-control/references/guest-socket.md
@@ -29,7 +29,7 @@ not there yet.
| `{"t":"screenshot","path":"/abs/shot.png"}` | Full-resolution capture to `path` (PNG or JPEG by extension). Without `path` it saves to the Desktop |
| `{"t":"tap","x":645,"y":1398}` | Tap |
| `{"t":"swipe","x1":645,"y1":2600,"x2":645,"y2":1400,"ms":300}` | Swipe; `ms` defaults to 300 |
-| `{"t":"key","name":"home"}` | `home`, `power`, `volup`, `voldown` are hardware HID keys. Any other name (`return`, `cmd+v`) goes to vphoned `input.key` |
+| `{"t":"key","name":"home"}` | `home`, `power`, `volup`, `voldown`, `side` (an Apple Watch's side button, consumer 0x95) are hardware HID keys. Any other name (`return`, `cmd+v`) goes to vphoned `input.key` |
| `{"t":"type","text":"Hello"}` | Sets the **guest clipboard**; it does not type |
| `{"t":"rpc","method":"<vphoned method>","params":{…}}` | Calls any vphoned method; see [rpc-methods](rpc-methods.md) |
| `{"t":"push","local":"/abs/host/file","path":"/abs/guest/file","mode":"755"}` | Streams a Mac file into the guest, any size. A `path` ending in `/` keeps the file's name; `mode` defaults to the Mac file's permissions. `result` has `path`, `local`, `size` |
diff --git a/VPhoneExecutable/VPhoneVirtualization/Resources/Localizable.xcstrings b/VPhoneExecutable/VPhoneVirtualization/Resources/Localizable.xcstrings
index d8fcdb49..318ec81a 100644
--- a/VPhoneExecutable/VPhoneVirtualization/Resources/Localizable.xcstrings
+++ b/VPhoneExecutable/VPhoneVirtualization/Resources/Localizable.xcstrings
@@ -10,6 +10,15 @@
"zh-Hans" : { "stringUnit" : { "state" : "translated", "value" : "控制中心" } }
}
},
+ "Side Button" : {
+ "localizations" : {
+ "en" : { "stringUnit" : { "state" : "translated", "value" : "Side Button" } },
+ "ja" : { "stringUnit" : { "state" : "translated", "value" : "サイドボタン" } },
+ "ko" : { "stringUnit" : { "state" : "translated", "value" : "측면 버튼" } },
+ "vi" : { "stringUnit" : { "state" : "translated", "value" : "Nút sườn" } },
+ "zh-Hans" : { "stringUnit" : { "state" : "translated", "value" : "侧边按钮" } }
+ }
+ },
"Show Attitude Dials" : {
"extractionState" : "manual",
"localizations" : {
diff --git a/VPhoneExecutable/VPhoneVirtualization/UI/UserInterface/Menu/VPhoneMenuController.swift b/VPhoneExecutable/VPhoneVirtualization/UI/UserInterface/Menu/VPhoneMenuController.swift
index 90f32efc..ee26e019 100644
--- a/VPhoneExecutable/VPhoneVirtualization/UI/UserInterface/Menu/VPhoneMenuController.swift
+++ b/VPhoneExecutable/VPhoneVirtualization/UI/UserInterface/Menu/VPhoneMenuController.swift
@@ -28,6 +28,12 @@ class VPhoneMenuController {
var showsTVControls = false {
didSet { tvControlCenterItem?.isHidden = !showsTVControls }
}
+ var watchSideButtonItem: NSMenuItem?
+
+ /// An Apple Watch guest has a side button beside the Digital Crown.
+ var showsWatchControls = false {
+ didSet { watchSideButtonItem?.isHidden = !showsWatchControls }
+ }
var onHardwareKeyboardChange: ((Bool) async throws -> Void)?
var onFrameRateDisplayChange: ((Bool) -> Void)?
/// Saves the unlock-at-startup setting to this machine's config.plist.
diff --git a/VPhoneExecutable/VPhoneVirtualization/UI/UserInterface/Menu/VPhoneMenuDevice.swift b/VPhoneExecutable/VPhoneVirtualization/UI/UserInterface/Menu/VPhoneMenuDevice.swift
index 7360dbef..ccf10462 100644
--- a/VPhoneExecutable/VPhoneVirtualization/UI/UserInterface/Menu/VPhoneMenuDevice.swift
+++ b/VPhoneExecutable/VPhoneVirtualization/UI/UserInterface/Menu/VPhoneMenuDevice.swift
@@ -43,6 +43,11 @@ extension VPhoneMenuController {
modifiers: [],
symbol: "arrow.uturn.backward",
))
+ // Shown only for an Apple Watch guest; see `showsWatchControls`.
+ let sideButton = makeItem("Side Button", action: #selector(sendWatchSideButton), symbol: "button.vertical.right.press")
+ sideButton.isHidden = true
+ watchSideButtonItem = sideButton
+ menu.addItem(sideButton)
menu.addItem(makeItem("Power", action: #selector(sendPower), symbol: "power"))
menu.addItem(makeItem("Volume Up", action: #selector(sendVolumeUp), symbol: "speaker.plus"))
menu.addItem(makeItem("Volume Down", action: #selector(sendVolumeDown), symbol: "speaker.minus"))
@@ -150,6 +155,10 @@ extension VPhoneMenuController {
captureView?.performBackGesture()
}
+ @objc func sendWatchSideButton() {
+ keySender.sendWatchSideButton()
+ }
+
@objc func sendPower() {
keySender.sendPower()
}
diff --git a/VPhoneExecutable/VPhoneVirtualization/UI/UserInterface/VPhoneVirtualMachineKeySender.swift b/VPhoneExecutable/VPhoneVirtualization/UI/UserInterface/VPhoneVirtualMachineKeySender.swift
index f35bdcf8..367b5f25 100644
--- a/VPhoneExecutable/VPhoneVirtualization/UI/UserInterface/VPhoneVirtualMachineKeySender.swift
+++ b/VPhoneExecutable/VPhoneVirtualization/UI/UserInterface/VPhoneVirtualMachineKeySender.swift
@@ -68,6 +68,15 @@ class VPhoneVirtualMachineKeySender {
}
}
+ /// An Apple Watch's side button is consumer Help (0x0C/0x95), the device
+ /// tree's `/buttons` "help" beside the crown's "menu". Carousel reads it
+ /// as the side button (Control Center, Wallet, SOS); consumer Power
+ /// (0x30) only sleeps or wakes the display there.
+ func sendWatchSideButton() {
+ guard requireConnection() else { return }
+ control.sendHIDPress(page: 0x0C, usage: 0x95)
+ }
+
func sendPower() {
guard requireConnection() else { return }
control.sendHIDPress(page: 0x0C, usage: 0x30)
diff --git a/VPhoneExecutable/VPhoneVirtualization/UI/VPhoneBootCommand+VirtualMachine.swift b/VPhoneExecutable/VPhoneVirtualization/UI/VPhoneBootCommand+VirtualMachine.swift
index b05a8c0a..efa2f052 100644
--- a/VPhoneExecutable/VPhoneVirtualization/UI/VPhoneBootCommand+VirtualMachine.swift
+++ b/VPhoneExecutable/VPhoneVirtualization/UI/VPhoneBootCommand+VirtualMachine.swift
@@ -33,6 +33,7 @@ extension VPhoneBootCommand {
kernelDebugPort: kernelDebugPort,
isPadGuest: manifest.guestDevice.isPad,
isTVGuest: manifest.guestDevice.family == .appleTV,
+ isWatchGuest: manifest.guestDevice.family == .watch,
)
}
}
diff --git a/VPhoneExecutable/VPhoneVirtualization/UI/VPhoneHostAutomationServer.swift b/VPhoneExecutable/VPhoneVirtualization/UI/VPhoneHostAutomationServer.swift
index 0ea6056a..717787a7 100644
--- a/VPhoneExecutable/VPhoneVirtualization/UI/VPhoneHostAutomationServer.swift
+++ b/VPhoneExecutable/VPhoneVirtualization/UI/VPhoneHostAutomationServer.swift
@@ -343,6 +343,7 @@ class VPhoneHostAutomationServer {
let hidKey: (page: UInt32, usage: UInt32)? = switch name {
case "home": (0x0C, 0x40)
case "power": (0x0C, 0x30)
+ case "side": (0x0C, 0x95) // An Apple Watch's side button.
case "volup": (0x0C, 0xE9)
case "voldown": (0x0C, 0xEA)
default: nil
diff --git a/VPhoneExecutable/VPhoneVirtualization/UI/VPhoneVirtualMachineAppDelegate.swift b/VPhoneExecutable/VPhoneVirtualization/UI/VPhoneVirtualMachineAppDelegate.swift
index 5871dd2b..2cd7dbe1 100644
--- a/VPhoneExecutable/VPhoneVirtualization/UI/VPhoneVirtualMachineAppDelegate.swift
+++ b/VPhoneExecutable/VPhoneVirtualization/UI/VPhoneVirtualMachineAppDelegate.swift
@@ -217,6 +217,7 @@ class VPhoneVirtualMachineAppDelegate: NSObject, NSApplicationDelegate {
}
mc.captureView = wc.captureView
mc.showsTVControls = options.isTVGuest
+ mc.showsWatchControls = options.isWatchGuest
mc.touchIDMonitor = wc.touchIDMonitor
mc.onFilesPressed = { [weak fileWC, weak control] in
guard let fileWC, let control else { return }
diff --git a/VPhoneExecutable/VPhoneVirtualization/UI/VirtualMachine/VPhoneVirtualMachine.swift b/VPhoneExecutable/VPhoneVirtualization/UI/VirtualMachine/VPhoneVirtualMachine.swift
index 6f13a16e..da0ea4b0 100644
--- a/VPhoneExecutable/VPhoneVirtualization/UI/VirtualMachine/VPhoneVirtualMachine.swift
+++ b/VPhoneExecutable/VPhoneVirtualization/UI/VirtualMachine/VPhoneVirtualMachine.swift
@@ -47,6 +47,9 @@ class VPhoneVirtualMachine: NSObject, VZVirtualMachineDelegate {
/// The guest runs iPadOS: Esc is a key there, not the back gesture.
var isPadGuest = false
var isTVGuest = false
+ /// The guest runs watchOS: its side button is a key of its own (consumer
+ /// Help), apart from the crown (Home) and the power key.
+ var isWatchGuest = false
}
private struct DeviceIdentity {