Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift

Add live gyroscope controls to the VM display app

Phineas Guo67a05e5f1ee8
diff --git a/Research/0_binary_patch_comparison.md b/Research/0_binary_patch_comparison.md
index 373ecf5f..d169a293 100644
--- a/Research/0_binary_patch_comparison.md
+++ b/Research/0_binary_patch_comparison.md
@@ -242,8 +242,13 @@
> a Darwin notification. There is no system executable, kernel or DSC byte
> change. Disabling the patch removes the added library; live environment
> sync cannot reinstall an absent selected library. A provider/library update
-> needs a reboot, without silently restarting backboardd. The host menu and
-> panel are deferred until the user approves the next task. HID enumeration
+> needs a reboot, without silently restarting backboardd. The VM display app's
+> Motion Sensors → 3D Gyroscope panel sends valid three-axis edits immediately,
+> with a simulation checkbox that retains values and a reset that zeros all
+> axes. `motion.gyroscope.set` accepts an optional Boolean `enabled` (default
+> true); the panel checks `motion_gyroscope_toggle` support. Writes serialize
+> and coalesce, preserve the latest values across old acknowledgements, and
+> retry pending state after reconnect. HID enumeration
> and dispatch are observable separately from CoreMotion app acceptance; the
> platform capability gate and optional IMU match still require guest proof.
> Reveal evidence and manual acceptance: `Research/Guest/virtual_gyroscope.md`.
diff --git a/Research/Guest/virtual_gyroscope.md b/Research/Guest/virtual_gyroscope.md
index bb486826..50bb6c97 100644
--- a/Research/Guest/virtual_gyroscope.md
+++ b/Research/Guest/virtual_gyroscope.md
@@ -4,13 +4,15 @@
The core adds raw three-axis angular velocity, in **radians per second**. It
does not represent Euler angles or synthesize accelerometer, compass, attitude,
-or fused `CMDeviceMotion`. The host menu and axis panel are a separate task.
+or fused `CMDeviceMotion`.
-`vphoned` exposes `motion.gyroscope.set {x,y,z}`, `motion.gyroscope.get`, and
+`vphoned` exposes `motion.gyroscope.set {x,y,z,enabled?}`, `motion.gyroscope.get`, and
`motion.gyroscope.clear` over the existing VSOCK 1339 RPC transport. Set requires
all three finite JSON numbers in [-1000,1000]; strings, Booleans, missing axes,
and out-of-range values are refused before any state is changed. Clear disables
-the configured rotation and writes zero on every axis.
+the configured rotation and writes zero on every axis. Set's optional `enabled`
+must be a JSON Boolean and defaults to true, preserving existing clients. False
+keeps the configured axes but makes the provider emit stationary samples.
One dictionary, `VPhoneGyroscopeConfiguration`, is written through cfprefsd to
the mobile user's `com.apple.backboardd` domain and then
@@ -43,6 +45,34 @@ seconds. The status includes service ID, PID, report interval, dispatched event
count, dispatch failures, last error, and the configuration consumed by the
provider. **Enumeration and dispatch do not prove CoreMotion acceptance.**
+## Host panel
+
+The VM display app's **Motion Sensors → 3D Gyroscope** menu opens a native
+SwiftUI panel (Chinese: **运动传感器 → 3D 陀螺仪**). Each axis has a text field
+and a 0.1 rad/s stepper. Valid edits are sent immediately; partial, non-finite
+and out-of-range text stays in the field with a validation message and is not
+sent. The checkbox enables/disables simulation without discarding axis values.
+**Reset** zeros all fields and sends the zero configuration, preserving the
+checkbox. Reset also repairs partially typed/invalid fields.
+
+The panel uses capability `motion_gyroscope_toggle`, so an older daemon which
+would ignore `enabled` cannot silently apply the wrong checkbox state. It reads
+the stored configuration on opening/reconnect, and keeps accepted local edits
+when reconnecting after a failed send. A single in-flight RPC and one pending
+full configuration coalesce rapid edits; disable and reset replace that pending
+state, and stale acknowledgements never replace newer field text. Failed writes
+remain unsynced with a retry action. Closing the panel does not drop a write
+already accepted by the UI. The existing window controller retains the model
+and uses `isReleasedWhenClosed = false`.
+
+The model test harness (`zsh VPhoneExecutable/VPhoneVirtualization/Tests/run-gyroscope-tests.sh`)
+exercises delayed acknowledgements, coalescing, reset/disable while a write is
+pending, invalid text, retry, reconnect, stale reads and decimal-comma input.
+On 2026-10-08 these tests, the disabled-state property-list round trip and HID
+event factory tests passed; the full `VPhone` bundle build also passed with the
+Chinese menu/panel strings compiled into its resources. Native UI interaction
+was not run after the local preview compilation request was declined.
+
## Patch selection and installation
`system-backboardd-cfw-gyroscope` is declared in the Guest System patch set and
diff --git a/Research/vphoned_http_api.md b/Research/vphoned_http_api.md
index 2b6ec817..8f48940c 100644
--- a/Research/vphoned_http_api.md
+++ b/Research/vphoned_http_api.md
@@ -295,7 +295,7 @@ request carries `"force": true`.
| System | `system.uicache`, `system.system_apps {visible?}`, `system.respring` **force**, `system.reboot {userspace?}` **force**, `system.shutdown` **force**, `developer_mode.status`, `developer_mode.enable`, `power.low_power_mode`, `time.timezone {identifier?, automatic?}` (see below), `diagnostics.self_test` |
| Files | `files.list`, `mkdir`, `remove`, `rename`, `read {binary?, limit?}`, `write`, `find`, `copy`, `symlink`, `chmod`, `chown`, `plist`, `plist_set {value \| remove}` |
| Preferences, clipboard, location | `settings.get/set/delete`, `clipboard.get/set/clear`, `location.set/clear/current` |
-| Motion | `motion.gyroscope.get`, `motion.gyroscope.set {x,y,z}`, `motion.gyroscope.clear` (capability `motion_gyroscope`; finite JSON numbers in [-1000,1000] rad/s, all axes required; returns configuration, `units`, `provider`, and `provider_running`; HID provider status is not proof of CoreMotion app delivery) |
+| Motion | `motion.gyroscope.get`, `motion.gyroscope.set {x,y,z,enabled?}`, `motion.gyroscope.clear` (capability `motion_gyroscope`; finite JSON numbers in [-1000,1000] rad/s, all axes required; `enabled` defaults to true and must be a JSON Boolean; capability `motion_gyroscope_toggle` supports disabling while retaining configured axes; returns configuration, `units`, `provider`, and `provider_running`; HID provider status is not proof of CoreMotion app delivery) |
| Keychain | `keychain.list {class?}`, `add`, `delete`, `get`, `update`, `database` |
| Packages (read-only) | `packages.list`, `status`, `info {path}`, `compare`, `tweaks`, `repos` |
| Bootstrap | `bootstrap.install {layout}`, `bootstrap.status`, `bootstrap.inspect`, `bootstrap.uninstall {jbroot, force}`, `bootstrap.firmware` (see above) |
diff --git a/VPhoneDaemon/Daemon/GuestAPI+Gyroscope.swift b/VPhoneDaemon/Daemon/GuestAPI+Gyroscope.swift
index d8972669..4cbe932a 100644
--- a/VPhoneDaemon/Daemon/GuestAPI+Gyroscope.swift
+++ b/VPhoneDaemon/Daemon/GuestAPI+Gyroscope.swift
@@ -17,7 +17,14 @@ extension GuestAPI {
defer { gyroscopeLock.unlock() }
if method != "motion.gyroscope.get" {
var axes = [Double](repeating: 0, count: 3)
+ var enabled = method == "motion.gyroscope.set"
if method == "motion.gyroscope.set" {
+ if let flag = params["enabled"] {
+ guard let value = flag as? NSNumber, CFGetTypeID(value) == CFBooleanGetTypeID() else {
+ throw GuestAPIError.invalidRequest("enabled must be a boolean")
+ }
+ enabled = value.boolValue
+ }
for (index, key) in ["x", "y", "z"].enumerated() {
guard let value = params[key] as? NSNumber,
CFGetTypeID(value) != CFBooleanGetTypeID(),
@@ -28,7 +35,7 @@ extension GuestAPI {
axes[index] = value.doubleValue
}
}
- guard vp_gyro_set(axes[0], axes[1], axes[2], method == "motion.gyroscope.set") else {
+ guard vp_gyro_set(axes[0], axes[1], axes[2], enabled) else {
throw GuestAPIError.operationFailed("Could not publish the gyroscope configuration")
}
}
diff --git a/VPhoneDaemon/Daemon/GuestAPI.swift b/VPhoneDaemon/Daemon/GuestAPI.swift
index d257a1a9..d5dc7cb4 100644
--- a/VPhoneDaemon/Daemon/GuestAPI.swift
+++ b/VPhoneDaemon/Daemon/GuestAPI.swift
@@ -141,6 +141,7 @@ enum GuestAPI {
"timezone",
"audio_host_latency",
"motion_gyroscope",
+ "motion_gyroscope_toggle",
],
]
}
diff --git a/VPhoneExecutable/VPhoneVirtualization/Resources/Localizable.xcstrings b/VPhoneExecutable/VPhoneVirtualization/Resources/Localizable.xcstrings
index 1133a84a..7dddadd1 100644
--- a/VPhoneExecutable/VPhoneVirtualization/Resources/Localizable.xcstrings
+++ b/VPhoneExecutable/VPhoneVirtualization/Resources/Localizable.xcstrings
@@ -1,6 +1,244 @@
{
"sourceLanguage" : "en",
"strings" : {
+ "%@ axis" : {
+ "extractionState" : "manual",
+ "localizations" : {
+ "en" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "%@ axis"
+ }
+ },
+ "zh-Hans" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "%@ 轴"
+ }
+ }
+ }
+ },
+ "3D Gyroscope" : {
+ "extractionState" : "manual",
+ "localizations" : {
+ "en" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "3D Gyroscope"
+ }
+ },
+ "zh-Hans" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "3D 陀螺仪"
+ }
+ }
+ }
+ },
+ "Angular Velocity" : {
+ "extractionState" : "manual",
+ "localizations" : {
+ "en" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "Angular Velocity"
+ }
+ },
+ "zh-Hans" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "角速度"
+ }
+ }
+ }
+ },
+ "Changes sync to the guest immediately. Disabling keeps your axis values." : {
+ "extractionState" : "manual",
+ "localizations" : {
+ "en" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "Changes sync to the guest immediately. Disabling keeps your axis values."
+ }
+ },
+ "zh-Hans" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "修改会实时同步给来宾。禁用时保留三轴设定。"
+ }
+ }
+ }
+ },
+ "Enable Simulation" : {
+ "extractionState" : "manual",
+ "localizations" : {
+ "en" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "Enable Simulation"
+ }
+ },
+ "zh-Hans" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "启用模拟"
+ }
+ }
+ }
+ },
+ "Enter a number from -1000 to 1000 for each axis." : {
+ "extractionState" : "manual",
+ "localizations" : {
+ "en" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "Enter a number from -1000 to 1000 for each axis."
+ }
+ },
+ "zh-Hans" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "每个轴请输入 -1000 到 1000 之间的数字。"
+ }
+ }
+ }
+ },
+ "Guest did not apply the gyroscope configuration" : {
+ "extractionState" : "manual",
+ "localizations" : {
+ "en" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "Guest did not apply the gyroscope configuration"
+ }
+ },
+ "zh-Hans" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "来宾未应用陀螺仪设定"
+ }
+ }
+ }
+ },
+ "Motion Sensors" : {
+ "extractionState" : "manual",
+ "localizations" : {
+ "en" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "Motion Sensors"
+ }
+ },
+ "zh-Hans" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "运动传感器"
+ }
+ }
+ }
+ },
+ "Reset" : {
+ "extractionState" : "manual",
+ "localizations" : {
+ "en" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "Reset"
+ }
+ },
+ "zh-Hans" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "复位"
+ }
+ }
+ }
+ },
+ "Retry" : {
+ "extractionState" : "manual",
+ "localizations" : {
+ "en" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "Retry"
+ }
+ },
+ "zh-Hans" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "重试"
+ }
+ }
+ }
+ },
+ "Set all three axes to zero" : {
+ "extractionState" : "manual",
+ "localizations" : {
+ "en" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "Set all three axes to zero"
+ }
+ },
+ "zh-Hans" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "将三个轴归零"
+ }
+ }
+ }
+ },
+ "Synced" : {
+ "extractionState" : "manual",
+ "localizations" : {
+ "en" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "Synced"
+ }
+ },
+ "zh-Hans" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "已同步"
+ }
+ }
+ }
+ },
+ "Syncing…" : {
+ "extractionState" : "manual",
+ "localizations" : {
+ "en" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "Syncing…"
+ }
+ },
+ "zh-Hans" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "正在同步…"
+ }
+ }
+ }
+ },
+ "Waiting for sensor service…" : {
+ "extractionState" : "manual",
+ "localizations" : {
+ "en" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "Waiting for sensor service…"
+ }
+ },
+ "zh-Hans" : {
+ "stringUnit" : {
+ "state" : "translated",
+ "value" : "等待运动传感器服务…"
+ }
+ }
+ }
+ },
"Use Hardware Keyboard" : {
"extractionState" : "manual",
"localizations" : {
diff --git a/VPhoneExecutable/VPhoneVirtualization/Tests/GyroscopeModelTests.swift b/VPhoneExecutable/VPhoneVirtualization/Tests/GyroscopeModelTests.swift
new file mode 100644
index 00000000..32e96e9e
--- /dev/null
+++ b/VPhoneExecutable/VPhoneVirtualization/Tests/GyroscopeModelTests.swift
@@ -0,0 +1,171 @@
+import Foundation
+
+@MainActor
+final class VPhoneGyroscopeTestGuest {
+ var reply = VPhoneGyroscopeReply(configuration: VPhoneGyroscopeConfiguration(), providerRunning: true)
+ var writes: [VPhoneGyroscopeConfiguration] = []
+ var completions: [CheckedContinuation<VPhoneGyroscopeReply, any Error>] = []
+ private var completed = 0
+
+ func write(_ value: VPhoneGyroscopeConfiguration) async throws -> VPhoneGyroscopeReply {
+ writes.append(value)
+ return try await withCheckedThrowingContinuation { completions.append($0) }
+ }
+
+ func finish(failing: Bool = false) {
+ let completion = completions.removeFirst()
+ let value = writes[completed]
+ completed += 1
+ if failing {
+ completion.resume(throwing: Failure.offline)
+ } else {
+ reply.configuration = value
+ completion.resume(returning: reply)
+ }
+ }
+
+ enum Failure: Error { case offline }
+}
+
+@main
+struct VPhoneGyroscopeModelTests {
+ @MainActor static func waitFor(_ predicate: () -> Bool) async {
+ for _ in 0 ..< 10000 {
+ if predicate() { return }
+ await Task.yield()
+ }
+ fatalError("Timed out waiting for the gyroscope request queue")
+ }
+
+ @MainActor static func main() async {
+ let guest = VPhoneGyroscopeTestGuest()
+ let model = VPhoneGyroscopeModel(locale: Locale(identifier: "en_US"), read: { guest.reply }, write: {
+ try await guest.write($0)
+ })
+ await model.connectionChanged(true)
+ assert(model.canEdit && !model.enabled && guest.writes.isEmpty)
+
+ // Rapid edits coalesce behind the single in-flight RPC. An old ack
+ // must neither overwrite newer field text nor skip the final value.
+ model.xText = "1"
+ await waitFor { guest.writes.count == 1 }
+ model.yText = "2"
+ model.zText = "-3"
+ model.enabled = true
+ assert(guest.writes.count == 1)
+ guest.finish()
+ await waitFor { guest.writes.count == 2 }
+ assert(guest.writes[1] == VPhoneGyroscopeConfiguration(enabled: true, x: 1, y: 2, z: -3))
+ assert(model.xText == "1" && model.yText == "2" && model.zText == "-3")
+ model.reset()
+ assert(model.enabled && model.xText == "0" && model.yText == "0" && model.zText == "0")
+ guest.finish()
+ await waitFor { guest.writes.count == 3 }
+ assert(guest.writes[2] == VPhoneGyroscopeConfiguration(enabled: true))
+ guest.finish()
+ await waitFor { !model.isSending }
+ assert(!model.hasLocalChanges && model.error == nil)
+
+ // Disable preserves configured axes; enable reuses them. A partial
+ // numeric edit must not prevent the safety-critical disable operation.
+ model.xText = "5"
+ await waitFor { guest.writes.count == 4 }
+ guest.finish()
+ await waitFor { !model.isSending }
+ model.enabled = false
+ await waitFor { guest.writes.count == 5 }
+ assert(!guest.writes[4].enabled && guest.writes[4].x == 5)
+ guest.finish()
+ await waitFor { !model.isSending }
+ model.enabled = true
+ await waitFor { guest.writes.count == 6 }
+ assert(guest.writes[5].enabled && guest.writes[5].x == 5)
+ guest.finish()
+ await waitFor { !model.isSending }
+ model.xText = "-"
+ model.yText = "nan"
+ model.zText = "1001"
+ assert(model.hasInvalidAxes && guest.writes.count == 6)
+ model.enabled = false
+ await waitFor { guest.writes.count == 7 }
+ assert(!guest.writes[6].enabled && guest.writes[6].x == 5)
+ guest.finish()
+ await waitFor { !model.isSending }
+ model.reset()
+ await waitFor { guest.writes.count == 8 }
+ assert(guest.writes[7] == VPhoneGyroscopeConfiguration())
+ assert(!model.hasInvalidAxes)
+ guest.finish()
+ await waitFor { !model.isSending }
+
+ // Keep the desired values on a failed write and retry the same full
+ // configuration, rather than presenting unacknowledged values as sent.
+ model.xText = "7"
+ await waitFor { guest.writes.count == 9 }
+ guest.finish(failing: true)
+ await waitFor { !model.isSending }
+ assert(model.canRetry && model.xText == "7" && model.hasLocalChanges)
+ model.retry()
+ await waitFor { guest.writes.count == 10 }
+ assert(guest.writes[9].x == 7)
+ guest.finish()
+ await waitFor { !model.isSending }
+ assert(!model.hasLocalChanges && model.error == nil)
+
+ // Disconnect during a write, then reconnect. The old request must
+ // finish before the pending state is resent, and cannot clear it.
+ model.zText = "9"
+ await waitFor { guest.writes.count == 11 }
+ await model.connectionChanged(false)
+ assert(!model.canEdit && !model.providerRunning)
+ guest.reply.configuration = VPhoneGyroscopeConfiguration()
+ await model.connectionChanged(true)
+ assert(model.zText == "9" && guest.writes.count == 11)
+ guest.finish()
+ await waitFor { guest.writes.count == 12 }
+ assert(guest.writes[11].x == 7 && guest.writes[11].z == 9)
+ guest.finish()
+ await waitFor { !model.isSending }
+ assert(!model.hasLocalChanges)
+
+ model.yText = "1"
+ await waitFor { guest.writes.count == 13 }
+ model.yText = "4"
+ guest.finish(failing: true)
+ await waitFor { guest.writes.count == 14 }
+ assert(guest.writes[13].y == 4)
+ guest.finish()
+ await waitFor { !model.isSending }
+ assert(model.error == nil && !model.hasLocalChanges)
+
+ // A cancelled/stale initial read cannot replace the new connection's
+ // values, nor can reading the guest itself trigger a write.
+ var reads: [CheckedContinuation<VPhoneGyroscopeReply, any Error>] = []
+ let reconnect = VPhoneGyroscopeModel(read: {
+ try await withCheckedThrowingContinuation { reads.append($0) }
+ }, write: { _ in fatalError("A read unexpectedly triggered a write") })
+ let first = Task { await reconnect.connectionChanged(true) }
+ await waitFor { reads.count == 1 }
+ await reconnect.connectionChanged(false)
+ let second = Task { await reconnect.connectionChanged(true) }
+ await waitFor { reads.count == 2 }
+ reads[1].resume(returning: VPhoneGyroscopeReply(
+ configuration: VPhoneGyroscopeConfiguration(enabled: true, x: 3), providerRunning: true,
+ ))
+ await second.value
+ reads[0].resume(returning: VPhoneGyroscopeReply(
+ configuration: VPhoneGyroscopeConfiguration(x: 99), providerRunning: false,
+ ))
+ await first.value
+ assert(reconnect.enabled && reconnect.xValue == 3 && reconnect.providerRunning)
+
+ let decimal = VPhoneGyroscopeModel(locale: Locale(identifier: "de_DE"), read: { guest.reply }, write: {
+ VPhoneGyroscopeReply(configuration: $0, providerRunning: true)
+ })
+ await decimal.connectionChanged(true)
+ decimal.xText = "1,25"
+ await waitFor { !decimal.hasLocalChanges }
+ assert(decimal.configuration.x == 1.25)
+ print("Gyroscope model tests passed: ordered/coalesced writes, toggle, reset, invalid input, retry, reconnect, stale reads, locale")
+ }
+}
diff --git a/VPhoneExecutable/VPhoneVirtualization/Tests/run-gyroscope-tests.sh b/VPhoneExecutable/VPhoneVirtualization/Tests/run-gyroscope-tests.sh
new file mode 100644
index 00000000..499a8e48
--- /dev/null
+++ b/VPhoneExecutable/VPhoneVirtualization/Tests/run-gyroscope-tests.sh
@@ -0,0 +1,12 @@
+#!/bin/zsh
+# vphone-tier: build
+set -euo pipefail
+
+root="$(cd "${0:a:h}/../../.." && pwd)"
+out="$root/.build/gyroscope-tests"
+mkdir -p "$out"
+xcrun --sdk macosx swiftc -swift-version 6 -parse-as-library \
+ -target arm64-apple-macos15.0 -module-cache-path "$out/module-cache" \
+ "$root/VPhoneExecutable/VPhoneVirtualization/UI/UserInterface/Panels/Gyroscope/VPhoneGyroscopeModel.swift" \
+ "${0:a:h}/GyroscopeModelTests.swift" -o "$out/GyroscopeModelTests"
+"$out/GyroscopeModelTests"
diff --git a/VPhoneExecutable/VPhoneVirtualization/UI/GuestCommunication/VPhoneGuestControlGyroscope.swift b/VPhoneExecutable/VPhoneVirtualization/UI/GuestCommunication/VPhoneGuestControlGyroscope.swift
new file mode 100644
index 00000000..3d0c0f43
--- /dev/null
+++ b/VPhoneExecutable/VPhoneVirtualization/UI/GuestCommunication/VPhoneGuestControlGyroscope.swift
@@ -0,0 +1,38 @@
+import CoreFoundation
+import Foundation
+
+// MARK: - Gyroscope RPC
+
+extension VPhoneGuestControl {
+ func readGyroscope() async throws -> VPhoneGyroscopeReply {
+ guard guestCapabilities.contains("motion_gyroscope_toggle") else {
+ throw ControlError.unsupportedCapability("motion_gyroscope_toggle")
+ }
+ let result = try await call("motion.gyroscope.get")
+ return try gyroscopeReply(result)
+ }
+
+ func setGyroscope(_ value: VPhoneGyroscopeConfiguration) async throws -> VPhoneGyroscopeReply {
+ guard guestCapabilities.contains("motion_gyroscope_toggle") else {
+ throw ControlError.unsupportedCapability("motion_gyroscope_toggle")
+ }
+ let result = try await call("motion.gyroscope.set", params: [
+ "enabled": value.enabled, "x": value.x, "y": value.y, "z": value.z,
+ ])
+ return try gyroscopeReply(result)
+ }
+
+ private func gyroscopeReply(_ result: [String: Any]) throws -> VPhoneGyroscopeReply {
+ guard let enabled = result["enabled"] as? NSNumber,
+ CFGetTypeID(enabled) == CFBooleanGetTypeID(),
+ let x = result["x"] as? NSNumber, let y = result["y"] as? NSNumber, let z = result["z"] as? NSNumber,
+ [x, y, z].allSatisfy({
+ CFGetTypeID($0) != CFBooleanGetTypeID() && $0.doubleValue.isFinite && abs($0.doubleValue) <= 1000
+ })
+ else { throw ControlError.protocolError("invalid gyroscope configuration") }
+ return VPhoneGyroscopeReply(
+ configuration: VPhoneGyroscopeConfiguration(enabled: enabled.boolValue, x: x.doubleValue, y: y.doubleValue, z: z.doubleValue),
+ providerRunning: result.bool("provider_running") ?? false,
+ )
+ }
+}
diff --git a/VPhoneExecutable/VPhoneVirtualization/UI/UserInterface/Menu/VPhoneMenuController.swift b/VPhoneExecutable/VPhoneVirtualization/UI/UserInterface/Menu/VPhoneMenuController.swift
index 0f26855c..54ed2205 100644
--- a/VPhoneExecutable/VPhoneVirtualization/UI/UserInterface/Menu/VPhoneMenuController.swift
+++ b/VPhoneExecutable/VPhoneVirtualization/UI/UserInterface/Menu/VPhoneMenuController.swift
@@ -142,6 +142,7 @@ class VPhoneMenuController {
// inspection and capture.
mainMenu.addItem(buildDeviceMenu())
mainMenu.addItem(buildFeaturesMenu())
+ mainMenu.addItem(buildMotionSensorsMenu())
mainMenu.addItem(buildDataMenu())
mainMenu.addItem(buildAppsMenu())
mainMenu.addItem(buildDiagnosticsMenu())
diff --git a/VPhoneExecutable/VPhoneVirtualization/UI/UserInterface/Menu/VPhoneMenuMotion.swift b/VPhoneExecutable/VPhoneVirtualization/UI/UserInterface/Menu/VPhoneMenuMotion.swift
new file mode 100644
index 00000000..3e9c7aa8
--- /dev/null
+++ b/VPhoneExecutable/VPhoneVirtualization/UI/UserInterface/Menu/VPhoneMenuMotion.swift
@@ -0,0 +1,14 @@
+import AppKit
+
+// MARK: - Motion Sensors
+
+extension VPhoneMenuController {
+ func buildMotionSensorsMenu() -> NSMenuItem {
+ let item = NSMenuItem(title: "Motion Sensors", action: nil, keyEquivalent: "")
+ let menu = NSMenu(title: "Motion Sensors")
+ menu.autoenablesItems = false
+ menu.addItem(makePanelItem(.gyroscope, "3D Gyroscope", keyEquivalent: "", symbol: "gyroscope"))
+ item.submenu = menu
+ return item
+ }
+}
diff --git a/VPhoneExecutable/VPhoneVirtualization/UI/UserInterface/Panels/Gyroscope/VPhoneGyroscopeModel.swift b/VPhoneExecutable/VPhoneVirtualization/UI/UserInterface/Panels/Gyroscope/VPhoneGyroscopeModel.swift
new file mode 100644
index 00000000..7326c283
--- /dev/null
+++ b/VPhoneExecutable/VPhoneVirtualization/UI/UserInterface/Panels/Gyroscope/VPhoneGyroscopeModel.swift
@@ -0,0 +1,193 @@
+import Foundation
+import Observation
+
+struct VPhoneGyroscopeConfiguration: Equatable, Sendable {
+ var enabled = false
+ var x = 0.0
+ var y = 0.0
+ var z = 0.0
+}
+
+struct VPhoneGyroscopeReply: Sendable {
+ var configuration: VPhoneGyroscopeConfiguration
+ var providerRunning: Bool
+}
+
+// MARK: - Live Gyroscope Controls
+
+@MainActor
+@Observable
+final class VPhoneGyroscopeModel {
+ var enabled = false {
+ didSet {
+ guard !applyingGuest, enabled != oldValue else { return }
+ // Disabling must work even while an axis contains a partial edit.
+ var value = parsedConfiguration ?? configuration
+ value.enabled = enabled
+ enqueue(value)
+ }
+ }
+ var xText = "0" { didSet { axesChanged() } }
+ var yText = "0" { didSet { axesChanged() } }
+ var zText = "0" { didSet { axesChanged() } }
+
+ private(set) var isConnected = false
+ private(set) var isReading = false
+ private(set) var isSending = false
+ private(set) var hasLoaded = false
+ private(set) var providerRunning = false
+ private(set) var error: String?
+ private(set) var hasLocalChanges = false
+ private(set) var configuration = VPhoneGyroscopeConfiguration()
+
+ @ObservationIgnored private let read: @MainActor () async throws -> VPhoneGyroscopeReply
+ @ObservationIgnored private let write: @MainActor (VPhoneGyroscopeConfiguration) async throws -> VPhoneGyroscopeReply
+ @ObservationIgnored private let locale: Locale
+ @ObservationIgnored private var applyingGuest = false
+ @ObservationIgnored private var generation = 0
+ @ObservationIgnored private var pending: VPhoneGyroscopeConfiguration?
+ @ObservationIgnored private var writer: Task<Void, Never>?
+
+ init(
+ locale: Locale = .current,
+ read: @escaping @MainActor () async throws -> VPhoneGyroscopeReply,
+ write: @escaping @MainActor (VPhoneGyroscopeConfiguration) async throws -> VPhoneGyroscopeReply,
+ ) {
+ self.locale = locale
+ self.read = read
+ self.write = write
+ }
+
+ var canEdit: Bool { isConnected && hasLoaded && !isReading }
+ var hasInvalidAxes: Bool { parsedConfiguration == nil }
+ var canRetry: Bool { canEdit && !isSending && hasLocalChanges && error != nil }
+
+ // Computed key-path bindings let the steppers repair a partially typed axis.
+ var xValue: Double {
+ get { number(xText) ?? configuration.x }
+ set { xText = formatted(newValue) }
+ }
+ var yValue: Double {
+ get { number(yText) ?? configuration.y }
+ set { yText = formatted(newValue) }
+ }
+ var zValue: Double {
+ get { number(zText) ?? configuration.z }
+ set { zText = formatted(newValue) }
+ }
+
+ private func number(_ text: String) -> Double? {
+ let normalized = text.trimmingCharacters(in: .whitespacesAndNewlines)
+ .replacingOccurrences(of: locale.decimalSeparator ?? ".", with: ".")
+ guard let value = Double(normalized), value.isFinite, abs(value) <= 1000 else { return nil }
+ return value
+ }
+
+ private func formatted(_ value: Double) -> String {
+ value.formatted(.number.grouping(.never).precision(.fractionLength(0 ... 6)).locale(locale))
+ }
+
+ private var parsedConfiguration: VPhoneGyroscopeConfiguration? {
+ guard let x = number(xText), let y = number(yText), let z = number(zText) else { return nil }
+ return VPhoneGyroscopeConfiguration(enabled: enabled, x: x, y: y, z: z)
+ }
+
+ private func axesChanged() {
+ guard !applyingGuest, let value = parsedConfiguration, value != configuration else { return }
+ enqueue(value)
+ }
+
+ private func applyFields(_ value: VPhoneGyroscopeConfiguration) {
+ applyingGuest = true
+ defer { applyingGuest = false }
+ enabled = value.enabled
+ xText = formatted(value.x)
+ yText = formatted(value.y)
+ zText = formatted(value.z)
+ configuration = value
+ }
+
+ func reset() {
+ guard canEdit else { return }
+ let zero = VPhoneGyroscopeConfiguration(enabled: enabled)
+ applyFields(zero)
+ enqueue(zero)
+ }
+
+ func retry() { startWriter() }
+
+ /// A read belongs to the view's connection task; an accepted edit's write
+ /// survives closing the panel. Never apply a read/ack from an old connection.
+ func connectionChanged(_ connected: Bool) async {
+ generation &+= 1
+ let current = generation
+ isConnected = connected
+ hasLoaded = false
+ if hasLocalChanges { pending = configuration }
+ guard connected else {
+ isReading = false
+ providerRunning = false
+ return
+ }
+ isReading = true
+ defer { if generation == current { isReading = false } }
+ do {
+ let reply = try await read()
+ guard generation == current, isConnected, !Task.isCancelled else { return }
+ providerRunning = reply.providerRunning
+ if !hasLocalChanges { applyFields(reply.configuration) }
+ hasLoaded = true
+ error = nil
+ startWriter()
+ } catch {
+ guard generation == current, !Task.isCancelled else { return }
+ self.error = String(describing: error)
+ }
+ }
+
+ private func enqueue(_ value: VPhoneGyroscopeConfiguration) {
+ guard canEdit else { return }
+ configuration = value
+ pending = value
+ hasLocalChanges = true
+ error = nil
+ startWriter()
+ }
+
+ private func startWriter() {
+ guard writer == nil, isConnected, hasLoaded, pending != nil else { return }
+ writer = Task { await drain() }
+ }
+
+ private func drain() async {
+ isSending = true
+ defer {
+ isSending = false
+ writer = nil
+ }
+ while isConnected, hasLoaded, let value = pending {
+ pending = nil
+ let current = generation
+ do {
+ let reply = try await write(value)
+ guard generation == current, isConnected else { continue }
+ providerRunning = reply.providerRunning
+ // The guest returns the persisted configuration, not merely
+ // transport success. Keep newer edits in the fields untouched.
+ guard reply.configuration == value else {
+ error = "Guest did not apply the gyroscope configuration"
+ pending = configuration
+ break
+ }
+ hasLocalChanges = pending != nil
+ error = nil
+ } catch {
+ guard generation == current, isConnected else { continue }
+ if pending != nil { continue } // A newer edit supersedes this failed write.
+ self.error = String(describing: error)
+ pending = configuration
+ break
+ }
+ }
+ }
+}
diff --git a/VPhoneExecutable/VPhoneVirtualization/UI/UserInterface/Panels/Gyroscope/VPhoneGyroscopeView.swift b/VPhoneExecutable/VPhoneVirtualization/UI/UserInterface/Panels/Gyroscope/VPhoneGyroscopeView.swift
new file mode 100644
index 00000000..ffa5053e
--- /dev/null
+++ b/VPhoneExecutable/VPhoneVirtualization/UI/UserInterface/Panels/Gyroscope/VPhoneGyroscopeView.swift
@@ -0,0 +1,120 @@
+import SwiftUI
+
+struct VPhoneGyroscopeView: View {
+ let model: VPhoneGyroscopeModel
+ let connected: @MainActor () -> Bool
+
+ var body: some View {
+ VPhoneGyroscopeEditor(model: model)
+ .task(id: connected()) { await model.connectionChanged(connected()) }
+ }
+}
+
+struct VPhoneGyroscopeEditor: View {
+ @Bindable var model: VPhoneGyroscopeModel
+
+ var body: some View {
+ VStack(spacing: 0) {
+ Form {
+ Section {
+ Toggle(isOn: $model.enabled) {
+ Text("Enable Simulation", bundle: VPhoneLocalization.bundle)
+ }
+ .toggleStyle(.checkbox)
+ .accessibilityIdentifier("gyroscope-enabled")
+ Text("Changes sync to the guest immediately. Disabling keeps your axis values.", bundle: VPhoneLocalization.bundle)
+ .font(.caption)
+ .foregroundStyle(.secondary)
+ }
+ Section {
+ VPhoneGyroscopeAxisRow(axis: "X", text: $model.xText, value: $model.xValue)
+ VPhoneGyroscopeAxisRow(axis: "Y", text: $model.yText, value: $model.yValue)
+ VPhoneGyroscopeAxisRow(axis: "Z", text: $model.zText, value: $model.zValue)
+ if model.hasInvalidAxes {
+ Text("Enter a number from -1000 to 1000 for each axis.", bundle: VPhoneLocalization.bundle)
+ .font(.caption)
+ .foregroundStyle(.orange)
+ }
+ Button { model.reset() } label: {
+ Label {
+ Text("Reset", bundle: VPhoneLocalization.bundle)
+ } icon: { Image(systemName: "arrow.counterclockwise") }
+ }
+ .accessibilityIdentifier("gyroscope-reset")
+ .help(Text("Set all three axes to zero", bundle: VPhoneLocalization.bundle))
+ } header: {
+ Text("Angular Velocity", bundle: VPhoneLocalization.bundle)
+ }
+ }
+ .formStyle(.grouped)
+ .disabled(!model.canEdit)
+ Divider()
+ VPhoneGyroscopeSyncStatus(model: model)
+ }
+ }
+}
+
+struct VPhoneGyroscopeAxisRow: View {
+ let axis: String
+ @Binding var text: String
+ @Binding var value: Double
+
+ var body: some View {
+ HStack(spacing: 8) {
+ Text(verbatim: axis)
+ .font(.system(.body, design: .monospaced))
+ TextField(axis, text: $text)
+ .textFieldStyle(.roundedBorder)
+ .font(.system(.body, design: .monospaced))
+ .accessibilityLabel(VPhoneLocalization.format("%@ axis", axis))
+ .accessibilityIdentifier("gyroscope-axis-" + axis.lowercased())
+ Text(verbatim: "rad/s").foregroundStyle(.secondary)
+ Stepper(axis, value: $value, in: -1000 ... 1000, step: 0.1)
+ .labelsHidden()
+ .accessibilityLabel(VPhoneLocalization.format("%@ axis", axis))
+ }
+ }
+}
+
+struct VPhoneGyroscopeSyncStatus: View {
+ let model: VPhoneGyroscopeModel
+
+ var body: some View {
+ HStack(spacing: 8) {
+ if !model.isConnected {
+ Text("Guest not connected", bundle: VPhoneLocalization.bundle)
+ } else if model.isReading || model.isSending {
+ ProgressView().controlSize(.small)
+ Text("Syncing…", bundle: VPhoneLocalization.bundle)
+ } else if let error = model.error {
+ Image(systemName: "exclamationmark.triangle").foregroundStyle(.orange)
+ Text(VPhoneLocalization.text(error)).textSelection(.enabled)
+ } else if model.hasLoaded {
+ Text(model.providerRunning ? "Synced" : "Waiting for sensor service…", bundle: VPhoneLocalization.bundle)
+ }
+ Spacer(minLength: 0)
+ if model.canRetry {
+ Button { model.retry() } label: { Text("Retry", bundle: VPhoneLocalization.bundle) }
+ } else if model.isConnected && !model.hasLoaded && !model.isReading {
+ Button { Task { await model.connectionChanged(true) } } label: {
+ Text("Retry", bundle: VPhoneLocalization.bundle)
+ }
+ }
+ }
+ .font(.system(.caption, design: .monospaced))
+ .padding(8)
+ .background(.bar)
+ }
+}
+
+#Preview {
+ let sample = VPhoneGyroscopeReply(
+ configuration: VPhoneGyroscopeConfiguration(enabled: true, x: 1.25, y: 0, z: -0.75),
+ providerRunning: true,
+ )
+ let model = VPhoneGyroscopeModel(read: { sample }, write: {
+ VPhoneGyroscopeReply(configuration: $0, providerRunning: true)
+ })
+ return VPhoneGyroscopeView(model: model, connected: { true })
+ .frame(width: 440, height: 380)
+}
diff --git a/VPhoneExecutable/VPhoneVirtualization/UI/UserInterface/Panels/VPhoneGuestPanelsWindowController.swift b/VPhoneExecutable/VPhoneVirtualization/UI/UserInterface/Panels/VPhoneGuestPanelsWindowController.swift
index ca96c4c6..9b92ba84 100644
--- a/VPhoneExecutable/VPhoneVirtualization/UI/UserInterface/Panels/VPhoneGuestPanelsWindowController.swift
+++ b/VPhoneExecutable/VPhoneVirtualization/UI/UserInterface/Panels/VPhoneGuestPanelsWindowController.swift
@@ -12,6 +12,7 @@ enum VPhoneGuestPanel: CaseIterable {
case crashLogs
case services
case controls
+ case gyroscope
/// The `/v1/health` capability an agent must report before the panel can
/// talk to it. Older agents answer "Unknown method" for everything else.
@@ -22,6 +23,7 @@ enum VPhoneGuestPanel: CaseIterable {
case .console, .crashLogs: "logs"
case .services: "services"
case .controls: "display"
+ case .gyroscope: "motion_gyroscope_toggle"
}
}
}
@@ -96,6 +98,17 @@ final class VPhoneGuestPanelsWindowController {
size: NSSize(width: 480, height: 640),
minSize: NSSize(width: 460, height: 400),
) { VPhoneControlsView(model: model) }
+ case .gyroscope:
+ let model = VPhoneGyroscopeModel(
+ read: { try await control.readGyroscope() },
+ write: { try await control.setGyroscope($0) },
+ )
+ return VPhoneGuestToolWindow(
+ title: String(localized: "3D Gyroscope", bundle: VPhoneLocalization.bundle),
+ autosaveName: "vphone-panel-gyroscope",
+ size: NSSize(width: 440, height: 380),
+ minSize: NSSize(width: 400, height: 340),
+ ) { VPhoneGyroscopeView(model: model, connected: { control.isConnected }) }
}
}
}
diff --git a/VPhoneGuestComponents/Tests/GyroscopeTests.m b/VPhoneGuestComponents/Tests/GyroscopeTests.m
index b7fd248e..d822321d 100644
--- a/VPhoneGuestComponents/Tests/GyroscopeTests.m
+++ b/VPhoneGuestComponents/Tests/GyroscopeTests.m
@@ -18,6 +18,14 @@ int main(void) {
assert(state.enabled && state.x == 1.25 && state.y == -2.5 && state.z == 0.125);
assert([VPhoneGyroscopeEncode(state) isEqual:sample]);
+ NSMutableDictionary *disabled = [sample mutableCopy];
+ disabled[@"enabled"] = @NO;
+ NSData *disabledWire = [NSPropertyListSerialization dataWithPropertyList:disabled
+ format:NSPropertyListBinaryFormat_v1_0 options:0 error:nil];
+ id disabledRead = [NSPropertyListSerialization propertyListWithData:disabledWire options:0 format:nil error:nil];
+ assert(VPhoneGyroscopeDecode(disabledRead, &state));
+ assert(!state.enabled && state.x == 1.25 && state.y == -2.5 && state.z == 0.125);
+
for (id invalid in @[@YES, @"1", NSNull.null, @(NAN), @(INFINITY), @1001, @-1001]) {
NSMutableDictionary *bad = [sample mutableCopy];
bad[@"y"] = invalid;