Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift

Wake and unlock a guest with screen.unlock

Jackyaa985d5ce507
diff --git a/Documents/Guides/launchpad-cli.md b/Documents/Guides/launchpad-cli.md
index 0fb46627..0b30134c 100644
--- a/Documents/Guides/launchpad-cli.md
+++ b/Documents/Guides/launchpad-cli.md
@@ -114,6 +114,7 @@ version while a machine is bound to it; rebind or delete those machines first.
| `cfw update-environment <name>` | Redeploy the machine's own bundle's guest resources (vphoned, hook dylibs) into it while stopped, through the helper; nothing else changes |
| `guest send <name> <json>` | One raw `vphone.sock` request (tap, swipe, key, screenshot) |
| `guest rpc <name> <method> [params]` | Any vphoned method, see `Research/vphoned_http_api.md` |
+| `guest unlock <name> [--passcode <code>] [--timeout <seconds>]` | Turn the screen on and unlock the guest, whatever state it was in (vphoned `screen.unlock`). `--passcode` is needed only when the guest has one |
| `exec [--bundle <version>] <vphone-cli arguments>` | Run the default bundle's `vphone-cli`, or that version's, streaming its output. `--bundle` must come first |
Machine commands take `--root <library>` when two libraries hold a machine
diff --git a/Research/Guest/screen_unlock.md b/Research/Guest/screen_unlock.md
new file mode 100644
index 00000000..e9b4d4ac
--- /dev/null
+++ b/Research/Guest/screen_unlock.md
@@ -0,0 +1,105 @@
+# Turning the screen on and unlocking
+
+vphoned's `screen.unlock` (`VPhoneDaemon/Daemon/GuestScreenUnlock.swift`,
+`VPhoneDaemon/Native/vphoned_unlock.m`) and `vphone-launchpad-cli guest unlock`.
+Measured on 2026-10-04 against `unlocktest-iphone` (iPhone17,3, iOS 27.0
+24A435, no passcode), with the 26.6.2 dyld shared cache for the static read.
+
+## Why a method
+
+A guest is at the Lock Screen after every boot, every SpringBoard restart and
+every press of the side button, and it is dark a few seconds later
+(`lock_screen_idle_timer.md`). A locked or dark screen swallows taps, and
+`apps.launch` answers `device_locked`.
+
+The hardware keys only toggle. `power` wakes a dark guest and darkens a lit
+one; `home` wakes, and on a lit Lock Screen without a passcode it dismisses to
+the Home Screen. A script has to read `device.screen` first and choose. The
+method does that reading and does only what each state needs.
+
+## What SpringBoard's own unlock request does, and why it is not used
+
+SpringBoardServices has `-[SBSLockScreenService
+requestPasscodeUnlockUIWithOptions:withCompletion:]` (`0x191f505c8` in the
+26.6.2 cache), the request an app makes when it needs an unlocked device.
+Served to a caller with `com.apple.springboard.requestDeviceUnlock` (the
+authenticator in `-[SBLockScreenService init]` is built with that entitlement
+string, at `0x224be0ae4`).
+
+Granting vphoned that entitlement and calling the request was tried first. The
+guest log shows why it does not unlock a passcode-free device:
+
+```
+unlockUIFromSource:ExternalRequest options:({SBUIUnlockOptionsTurnOnScreenFirstKey: 1}) screenWasOff:YES
+Bailing from UIUnlock because: turnOnScreenFirst = 1; autoUnlock = 0; shouldTurnOnScreen = 1
+```
+
+Asked while the screen is off, SpringBoard treats the request as *turn the
+screen on first*: it lights the backlight and bails out of the unlock
+(`autoUnlock = 0`), leaving the Lock Screen up. A second request, with the
+screen now on, did not dismiss it either. The request is the wrong tool for a
+passcode-free guest, and it needs a private entitlement. Both were dropped.
+
+## What `screen.unlock` does
+
+1. Reads `com.apple.springboard.lockstate` and
+ `com.apple.springboard.hasBlankedScreen` (IcliKit's `lockState()`). Until
+ `com.apple.springboard.finishedstartup` is non-zero these read
+ "unlocked, lit" no matter what will show, so at startup it waits for that
+ notification before trusting them.
+2. Not locked, only dark: `SBSUndimScreen`, and done. This lights the display
+ with no toggle and needs no entitlement (it is what icli's `wake` calls).
+3. Locked: if dark, `SBSUndimScreen` first so the next step lands on a live
+ Lock Screen. Then press Home.
+ - No passcode: Home dismisses the Lock Screen. Repeated until unlocked or
+ the deadline, in case the first press landed while the display was still
+ coming up.
+ - Passcode: Home raises the passcode pad; `passcode` is typed (digits as
+ keyboard number keys `0x1E`–`0x27`, anything else as text), with Return
+ if the pad has not submitted after a second.
+4. Polls the two notify states every 100 ms until lit and (if it was locked)
+ unlocked, or `timeout` (10 s by default, 1–60) runs out.
+
+Result: `{locked, screen_off, was_locked, was_screen_off}`; capability
+`screen_unlock`. No private entitlement.
+
+## Live results (no-passcode guest)
+
+All on `unlocktest-iphone`, each followed by `device.screen` and
+`apps.foreground`:
+
+| State before | `guest unlock` | After |
+| --- | --- | --- |
+| just booted, dark Lock Screen | ok, `was_screen_off:true was_locked:true` | Home Screen, lit |
+| lit, unlocked | ok, all `false` | unchanged |
+| `power` → dark + locked | ok | Home Screen, lit |
+| same, repeated | ok | Home Screen, lit |
+| lit Lock Screen (`was_screen_off:false`) | ok | unlocked; `apps.launch` Settings then `frontmost_verified:true` |
+| after `system.respring` → Lock Screen | ok | Home Screen, lit |
+
+So the device is actually usable afterwards, not merely reporting unlocked.
+
+## Not yet measured
+
+- **Passcode guests.** Setting a passcode on a research guest is not
+ automated, so the Home-raises-the-pad-then-type path is unrun. It is written
+ to the behavior of a real device (Home/menu raises passcode entry); treat it
+ as untested until a passcode guest is available.
+- iPadOS, and iOS 27.0.1 (its guests kernel-panic at first boot, separate
+ issue).
+
+## Reproducing
+
+```sh
+vphone-launchpad-cli guest send <vm> '{"t":"key","name":"power","screen":false}' # dark + locked
+vphone-launchpad-cli guest rpc <vm> device.screen # locked, screen_off
+vphone-launchpad-cli guest unlock <vm>
+vphone-launchpad-cli guest rpc <vm> device.screen
+vphone-launchpad-cli guest rpc <vm> apps.foreground
+```
+
+The `Bailing from UIUnlock` evidence, if the request path is revisited:
+
+```sh
+vphone-launchpad-cli guest rpc <vm> logs.syslog '{"seconds":8,"process":"SpringBoard","max_lines":5000}'
+```
diff --git a/Research/vphoned_http_api.md b/Research/vphoned_http_api.md
index 92566d45..f3eee25f 100644
--- a/Research/vphoned_http_api.md
+++ b/Research/vphoned_http_api.md
@@ -270,7 +270,7 @@ request carries `"force": true`.
| Area | Methods |
| --- | --- |
| Device | `device.snapshot`, `device.info` (snapshot plus network, screen, rotation, brightness, volume, low power, Developer Mode, agent), `device.screen`, `device.network`, `device.ioreg {plane}`, `device.environment`, `device.basebin {archive?}` |
-| Display, audio | `display.brightness {value?}`, `display.rotation {orientation?}`, `display.orientation` (`{degrees, source}`: SpringBoard's interface orientation without a screen capture, for polling; capability `display_orientation`), `display.rotation_lock {locked}`, `display.auto_lock` (`{auto_lock_seconds, never, lock_screen_minimum_seconds}`: Auto-Lock and the Lock Screen timeout vphoned keeps in step with it, see below; capability `display_auto_lock`), `audio.volume {value?, category?}`, `audio.state` |
+| Display, audio | `display.brightness {value?}`, `display.rotation {orientation?}`, `display.orientation` (`{degrees, source}`: SpringBoard's interface orientation without a screen capture, for polling; capability `display_orientation`), `display.rotation_lock {locked}`, `display.auto_lock` (`{auto_lock_seconds, never, lock_screen_minimum_seconds}`: Auto-Lock and the Lock Screen timeout vphoned keeps in step with it, see below; capability `display_auto_lock`), `screen.unlock {passcode?, timeout?}` (`{locked, screen_off, was_locked, was_screen_off}`: the display on and the Lock Screen passed, see below; capability `screen_unlock`), `audio.volume {value?, category?}`, `audio.state` |
| Input | `input.touch`, `input.hid`, `input.button {name}`, `input.key {name}`, `input.type {text, delay_ms?}`, `input.paste {text}`, `input.tap`, `input.double_tap`, `input.long_press`, `input.swipe`, `input.drag {points}`, `input.touch_sequence {events}` — gesture coordinates are screen points |
| UI | `ui.tree` (alias `accessibility.tree`), `ui.element_at`, `ui.tap_element`, `ui.wait`, `ui.wait_gone`, `ui.ocr {languages?, min_confidence?}`, `ui.describe`, `screen.screenshot` |
| Processes | `processes.list {filter?}`, `processes.kill {pid, signal?}` **force**, `memory.jetsam`, `memory.pressure` (only the three kernel memory sysctls, for polling) |
@@ -299,6 +299,16 @@ and whenever the settings change. SpringBoard reads the key when it starts, so
a newly written one holds from the next boot or respring. Measurements:
`Research/Guest/lock_screen_idle_timer.md`.
+`screen.unlock` reads the lock state, then turns the display on with
+`SBSUndimScreen` (no toggle, unlike a power press) and presses Home to dismiss
+the Lock Screen: a passcode-free guest goes to the Home Screen, a guest with a
+passcode gets the passcode pad, into which `passcode` is typed
+(`VPhoneDaemon/Daemon/GuestScreenUnlock.swift`). A lit, unlocked guest returns
+at once; a dark but unlocked one is only woken. A guest with a passcode needs
+`passcode`, entered once and never retried; without it the call fails before
+any key is sent. It needs no private entitlement. `timeout` is 1–60 seconds,
+10 by default. Measurements: `Research/Guest/screen_unlock.md`.
+
`network.ipv4.get` and `network.ipv4.set` read and write the IPv4 settings of
one interface (default `en0`) in configd's network preferences,
`/var/preferences/SystemConfiguration/preferences.plist`, through SCPreferences
@@ -345,7 +355,7 @@ Account passwords, boot logo rendering and package installation, removal and
repository changes are deliberately not exposed. `/v1/health` lists the new
areas in `capabilities` (`device_info`, `display`, `audio`, `input_gestures`,
`ui_inspection`, `processes`, `services`, `logs`, `network_capture`,
-`app_details`, `system_control`, `file_tools`, `packages`, `environment_update`, `udid_override`, `setup_skip`, `network_ipv4`, `network_hostname`, `network_static_names`, `network_resolve`, `display_auto_lock`) so a host can hide
+`app_details`, `system_control`, `file_tools`, `packages`, `environment_update`, `udid_override`, `setup_skip`, `network_ipv4`, `network_hostname`, `network_static_names`, `network_resolve`, `display_auto_lock`, `screen_unlock`) so a host can hide
panels an older agent cannot serve. icli failures reach the caller with
icli's own error `code` (`failed`, `unavailable`, `device_locked`, …) and
message.
diff --git a/Skills/vphone-guest-control/references/guest-socket.md b/Skills/vphone-guest-control/references/guest-socket.md
index 83f6607e..d8631319 100644
--- a/Skills/vphone-guest-control/references/guest-socket.md
+++ b/Skills/vphone-guest-control/references/guest-socket.md
@@ -74,7 +74,9 @@ paste for long or non-ASCII text.
## Patterns that work
-- **Wake and unlock check:** `ping`, then `screenshot` to a file and look at it.
+- **Wake and unlock:** `vphone-launchpad-cli guest unlock myphone` (add
+ `--passcode` when the guest has one). It works from any state; the keys only
+ toggle. Check with `ping`, then `screenshot` to a file and look at it.
- **Home:** `{"t":"key","name":"home"}`; **power** wakes or locks.
- **Open an app without hunting for its icon:** `apps.launch` with the bundle id.
- **Scroll a list:** swipe from lower to upper y, e.g. 2600 → 1400 at x 645.
diff --git a/Skills/vphone-guest-control/references/rpc-methods.md b/Skills/vphone-guest-control/references/rpc-methods.md
index f533b820..86bec2eb 100644
--- a/Skills/vphone-guest-control/references/rpc-methods.md
+++ b/Skills/vphone-guest-control/references/rpc-methods.md
@@ -53,6 +53,7 @@ invalid-request error, read the source named there instead of guessing keys.
| `display.brightness`, `audio.volume` | `value?` | Omit `value` to read |
| `display.rotation`, `display.orientation` | `orientation?` | |
| `display.auto_lock` | none | Auto-Lock in seconds (`never` when it is Never) and the Lock Screen timeout vphoned sets to match |
+| `screen.unlock` | `passcode?`, `timeout?` (10) | Display on and Lock Screen passed, from any state; `guest unlock <machine>` calls it. `passcode` only for a guest that has one, entered once |
| `device.ioreg` | `plane` | e.g. `IODeviceTree` |
## Input
diff --git a/Skills/vphone-guest-control/references/troubleshooting.md b/Skills/vphone-guest-control/references/troubleshooting.md
index 98d19da9..89c60275 100644
--- a/Skills/vphone-guest-control/references/troubleshooting.md
+++ b/Skills/vphone-guest-control/references/troubleshooting.md
@@ -59,7 +59,8 @@ notes.
machine and run `cfw update-environment <name>`.
- **`ok` but nothing changed on screen:** inputs are asynchronous; wait for the
attached `image` or take a screenshot. A locked or asleep screen swallows
- taps: press `power`, then `home`.
+ taps: run `guest unlock <name>`, or on an older vphoned press `power`, then
+ `home`.
- **Taps land in the wrong place:** the socket takes pixels (1290×2796); the
`input.*` RPCs take points. Use `ui.tree` / `ui.tap_element` instead.
- **Port 22 refused over iproxy:** no sshd yet. Use RPC; see
@@ -84,7 +85,8 @@ migration is hung, not that the display is broken.
## Apps and the bootstrap
-- **"Press home to continue" lock screen:** `{"t":"key","name":"home"}`.
+- **"Press home to continue" lock screen:** `guest unlock <name>`, or
+ `{"t":"key","name":"home"}`.
- **App crashes with `EXC_GUARD` / Mach port guard:** a known kernel-patch
scope limit on 26.x bases; see `Documents/Guides/troubleshooting.md`.
- **`dyld ... @loader_path/.jbroot/...` crash** after installing a package:
diff --git a/VPhoneDaemon/Daemon/GuestAPI+Device.swift b/VPhoneDaemon/Daemon/GuestAPI+Device.swift
index 3020c2f2..9826bf07 100644
--- a/VPhoneDaemon/Daemon/GuestAPI+Device.swift
+++ b/VPhoneDaemon/Daemon/GuestAPI+Device.swift
@@ -72,6 +72,11 @@ extension GuestAPI {
return try setRotationLock(locked)
case "display.auto_lock":
return GuestLockScreenIdle.describe()
+ case "screen.unlock":
+ return try GuestScreenUnlock.unlock(
+ passcode: optionalString(params, "passcode"),
+ timeout: number(params, "timeout", default: 10),
+ )
case "audio.volume":
let category = optionalString(params, "category") ?? "Audio/Video"
if params["value"] != nil {
diff --git a/VPhoneDaemon/Daemon/GuestAPI.swift b/VPhoneDaemon/Daemon/GuestAPI.swift
index 57a37164..667d6e35 100644
--- a/VPhoneDaemon/Daemon/GuestAPI.swift
+++ b/VPhoneDaemon/Daemon/GuestAPI.swift
@@ -100,6 +100,7 @@ enum GuestAPI {
"display",
"display_orientation",
"display_auto_lock",
+ "screen_unlock",
"audio",
"input_gestures",
"ui_inspection",
diff --git a/VPhoneDaemon/Daemon/GuestScreenUnlock.swift b/VPhoneDaemon/Daemon/GuestScreenUnlock.swift
new file mode 100644
index 00000000..d4e99c09
--- /dev/null
+++ b/VPhoneDaemon/Daemon/GuestScreenUnlock.swift
@@ -0,0 +1,166 @@
+import Foundation
+import IcliKit
+import notify
+import VphonedNative
+
+/// `screen.unlock`: turn the display on and get past the Lock Screen.
+///
+/// A guest is at the Lock Screen, dark, after every boot, every SpringBoard
+/// restart and every press of the side button, and a locked or dark screen
+/// swallows taps and refuses app launches. The hardware keys only toggle, so a
+/// script cannot tell what a press will do; this reads the state first and
+/// does only what is needed.
+///
+/// The display comes on through `SBSUndimScreen`, which lights it without the
+/// toggle a power press has. The Home button then dismisses the Lock Screen:
+/// on a device without a passcode it goes straight to the Home Screen, and on
+/// one with a passcode it raises the passcode pad, into which the passcode is
+/// typed as keyboard events. SpringBoard's own `requestPasscodeUnlock` request
+/// is not used: on a passcode-free device it lights the screen but leaves the
+/// Lock Screen up (`autoUnlock = 0`), so it cannot replace the Home press.
+///
+/// See Research/Guest/screen_unlock.md.
+enum GuestScreenUnlock {
+ /// Two unlocks at once would press Home and type over each other.
+ private static let exclusive = NSLock()
+ private static let pollInterval = 0.1
+ /// How long SpringBoard takes to raise the passcode pad after Home.
+ private static let padDelay = 1.0
+
+ static func unlock(passcode: String?, timeout: Double) throws -> [String: Any] {
+ guard timeout.isFinite, (1 ... 60).contains(timeout) else {
+ throw GuestAPIError.invalidRequest("timeout must be 1–60 seconds")
+ }
+ exclusive.lock()
+ defer { exclusive.unlock() }
+
+ let deadline = Date().addingTimeInterval(timeout)
+ let before = startingState(until: deadline)
+
+ if before.locked {
+ let lock = try collectDeviceSnapshot()["lock"] as? [String: Any]
+ let hasPasscode = lock?["passcode_enabled"] as? Bool ?? false
+ if hasPasscode, passcode == nil {
+ throw GuestAPIError.operationFailed("the device has a passcode; pass it as passcode")
+ }
+ try unlock(hasPasscode: hasPasscode, passcode: passcode, deadline: deadline)
+ } else if before.screenOff {
+ // Lit screen, already unlocked: just wake it.
+ _ = vp_screen_undim()
+ }
+
+ guard wait(until: deadline, for: { !$0.screenOff }) else {
+ throw GuestAPIError.operationFailed("the display did not turn on within \(Int(timeout)) s")
+ }
+
+ let after = state()
+ return [
+ "locked": after.locked,
+ "screen_off": after.screenOff,
+ "was_locked": before.locked,
+ "was_screen_off": before.screenOff,
+ ]
+ }
+
+ // MARK: - Lock Screen
+
+ private static func unlock(hasPasscode: Bool, passcode: String?, deadline: Date) throws {
+ // Light the screen first so the Home press lands on a live Lock
+ // Screen rather than only waking it.
+ if state().screenOff {
+ _ = vp_screen_undim()
+ _ = wait(until: min(Date().addingTimeInterval(1), deadline), for: { !$0.screenOff })
+ }
+
+ if hasPasscode, let passcode {
+ _ = try pressButton("home")
+ try enter(passcode, deadline: deadline)
+ guard wait(until: deadline, for: { !$0.locked }) else {
+ throw GuestAPIError.operationFailed("the device is still locked; the passcode was not accepted")
+ }
+ return
+ }
+
+ // No passcode: a Home press dismisses the Lock Screen. It is repeated
+ // in case the first one landed while the display was still coming up.
+ while state().locked {
+ guard Date() < deadline else {
+ throw GuestAPIError.operationFailed("the Lock Screen did not dismiss in time")
+ }
+ _ = try pressButton("home")
+ _ = wait(until: min(Date().addingTimeInterval(0.6), deadline), for: { !$0.locked })
+ }
+ }
+
+ /// Types the passcode into the pad Home raised. Digits go as the number
+ /// keys of a hardware keyboard, which the numeric pad takes; anything else
+ /// as text. A numeric pad submits on its last digit; a custom or
+ /// alphanumeric one waits for Return.
+ private static func enter(_ passcode: String, deadline: Date) throws {
+ Thread.sleep(forTimeInterval: padDelay)
+ guard state().locked else { return }
+ let digits = passcode.unicodeScalars.map { ("0" ... "9").contains($0) ? Int($0.value) - 0x30 : -1 }
+ if digits.allSatisfy({ $0 >= 0 }) {
+ for digit in digits {
+ // Keyboard page: 1…9 are 0x1E…0x26, 0 is 0x27.
+ _ = try hidPress(page: 0x07, usage: digit == 0 ? 0x27 : 0x1D + digit)
+ Thread.sleep(forTimeInterval: 0.06)
+ }
+ } else {
+ _ = try typeText(passcode, delayMS: 60)
+ }
+ let submitted = min(Date().addingTimeInterval(1), deadline)
+ if wait(until: submitted, for: { !$0.locked }) {
+ return
+ }
+ _ = try pressKey("return")
+ }
+
+ // MARK: - State
+
+ private struct State {
+ let locked: Bool
+ let screenOff: Bool
+ }
+
+ private static func state() -> State {
+ let state = lockState()
+ return State(
+ locked: state["locked"] as? Bool ?? false,
+ screenOff: state["screen_off"] as? Bool ?? false,
+ )
+ }
+
+ /// The state to start from. Until SpringBoard has finished starting, the
+ /// two notify states read "unlocked and lit" whatever the screen will
+ /// show, so that reading is trusted only once SpringBoard says it is up.
+ private static func startingState(until deadline: Date) -> State {
+ while true {
+ let now = state()
+ if now.locked || now.screenOff || springBoardStarted() || Date() >= deadline {
+ return now
+ }
+ Thread.sleep(forTimeInterval: pollInterval)
+ }
+ }
+
+ /// SpringBoard stores a non-zero state under this name when its startup
+ /// is over.
+ private static func springBoardStarted() -> Bool {
+ var token: Int32 = 0
+ guard notify_register_check("com.apple.springboard.finishedstartup", &token) == 0 else { return true }
+ defer { notify_cancel(token) }
+ var value: UInt64 = 0
+ return notify_get_state(token, &value) != 0 || value != 0
+ }
+
+ private static func wait(until deadline: Date, for condition: (State) -> Bool) -> Bool {
+ while true {
+ if condition(state()) {
+ return true
+ }
+ guard Date() < deadline else { return false }
+ Thread.sleep(forTimeInterval: pollInterval)
+ }
+ }
+}
diff --git a/VPhoneDaemon/Native/Include/VphonedNative.h b/VPhoneDaemon/Native/Include/VphonedNative.h
index 906aec95..ac4510c4 100644
--- a/VPhoneDaemon/Native/Include/VphonedNative.h
+++ b/VPhoneDaemon/Native/Include/VphonedNative.h
@@ -26,6 +26,10 @@ bool vp_hid_load(void);
/// `touchSequence` can carry two fingers at once, which is why this exists.
void vp_hid_touch2(int phase, double x1, double y1, double x2, double y2);
+/// Turn the display on without pressing a button. False when
+/// SpringBoardServices has no SBSUndimScreen.
+bool vp_screen_undim(void);
+
typedef struct {
int32_t pid;
int32_t ppid;
diff --git a/VPhoneDaemon/Native/vphoned_unlock.m b/VPhoneDaemon/Native/vphoned_unlock.m
new file mode 100644
index 00000000..ba56140a
--- /dev/null
+++ b/VPhoneDaemon/Native/vphoned_unlock.m
@@ -0,0 +1,27 @@
+/*
+ * vphoned_unlock — turn the guest display on.
+ *
+ * SpringBoardServices' SBSUndimScreen lights the display without the toggle a
+ * power-key press has. It is the same call icli's `wake` uses, and needs no
+ * entitlement. Getting past the Lock Screen itself is a Home press, driven
+ * from Swift (GuestScreenUnlock).
+ *
+ * The symbol is resolved at run time, so a base without it still starts and
+ * the call reports false instead.
+ */
+
+#import "Include/VphonedNative.h"
+
+#include <dlfcn.h>
+
+bool vp_screen_undim(void) {
+ static void *handle;
+ static dispatch_once_t once;
+ dispatch_once(&once, ^{
+ handle = dlopen("/System/Library/PrivateFrameworks/SpringBoardServices.framework/SpringBoardServices", RTLD_NOW);
+ });
+ void (*undim)(void) = handle ? dlsym(handle, "SBSUndimScreen") : NULL;
+ if (!undim) return false;
+ undim();
+ return true;
+}
diff --git a/VPhoneLaunchpad/VPhoneLaunchpad/Control/VPhoneLaunchpadControlCommands.swift b/VPhoneLaunchpad/VPhoneLaunchpad/Control/VPhoneLaunchpadControlCommands.swift
index 47b1f276..e8ed17dd 100644
--- a/VPhoneLaunchpad/VPhoneLaunchpad/Control/VPhoneLaunchpadControlCommands.swift
+++ b/VPhoneLaunchpad/VPhoneLaunchpad/Control/VPhoneLaunchpadControlCommands.swift
@@ -61,6 +61,7 @@ struct VPhoneLaunchpadControlCommands {
case "cfw.update-environment": return try await updateGuestEnvironment(request, emit: emit)
case "guest.send": return try await sendToGuest(request)
case "guest.rpc": return try await callGuest(request)
+ case "guest.unlock": return try await unlockGuest(request)
case "exec": return try await exec(request, emit: emit)
default: throw VPhoneLaunchpadError("\(command.name) is not handled by this Launchpad.")
}
@@ -723,6 +724,33 @@ struct VPhoneLaunchpadControlCommands {
return try await VPhoneLaunchpadGuestSocket.send(object, socketPath: Self.controlSocket(machine))
}
+ /// vphoned's `screen.unlock`: the display on and the Lock Screen passed,
+ /// whatever state the guest was in.
+ private func unlockGuest(_ request: VPhoneLaunchpadControlRequest) async throws -> Any {
+ let machine = try await machine(request)
+ var params: [String: Any] = [:]
+ if let passcode = request.option("passcode") {
+ params["passcode"] = passcode
+ }
+ if let text = request.option("timeout") {
+ guard let seconds = Double(text), (1 ... 60).contains(seconds) else {
+ throw VPhoneLaunchpadError("--timeout takes 1 to 60 seconds.")
+ }
+ params["timeout"] = seconds
+ }
+ let object: [String: Any] = ["t": "rpc", "method": "screen.unlock", "params": params]
+ do {
+ return try await VPhoneLaunchpadGuestSocket.send(object, socketPath: Self.controlSocket(machine))
+ } catch let error as VPhoneLaunchpadError where error.detail?.contains("Unknown method") == true {
+ // The guest environment is its own layer; an older vphoned stays
+ // in a machine until it is redeployed.
+ throw VPhoneLaunchpadError(
+ "The vphoned in \(machine.name) cannot unlock the screen.",
+ detail: "Its guest environment is older than screen.unlock. Stop the machine and run cfw update-environment with a Core Bundle that has it.",
+ )
+ }
+ }
+
// MARK: - vphone-cli
/// Runs the default bundle's `vphone-cli`, or that of `--bundle`. A
diff --git a/VPhoneLaunchpad/VPhoneLaunchpadShared/VPhoneLaunchpadControl.swift b/VPhoneLaunchpad/VPhoneLaunchpadShared/VPhoneLaunchpadControl.swift
index ee449d68..6aaea4bb 100644
--- a/VPhoneLaunchpad/VPhoneLaunchpadShared/VPhoneLaunchpadControl.swift
+++ b/VPhoneLaunchpad/VPhoneLaunchpadShared/VPhoneLaunchpadControl.swift
@@ -182,6 +182,8 @@ nonisolated struct VPhoneLaunchpadControlCommand: Sendable {
summary: "Send one raw vphone.sock request, such as {\"t\":\"tap\",\"x\":645,\"y\":1398}."),
Self(name: "guest.rpc", arguments: ["name", "method", "params..."], options: ["root"], flags: ["screen"],
summary: "Call a vphoned method; params is one JSON object."),
+ Self(name: "guest.unlock", arguments: ["name"], options: ["root", "passcode", "timeout"], flags: [],
+ summary: "Turn the screen on and unlock the guest (vphoned screen.unlock). --passcode enters the passcode of a guest that has one; --timeout is in seconds, 10 by default."),
Self(name: "exec", arguments: ["arguments..."], options: ["bundle"], flags: [],
summary: "Run vphone-cli with these arguments and stream its output: the default bundle's, or that of --bundle <version> given before the arguments."),