android-device is the canonical project-neutral adapter for an authorized
physical Android phone or tablet. It keeps Android Debug Bridge as the native
transport and adds exact handheld selection, minimized common readiness,
keyguard/user-storage observation, bounded lifecycle and deployment commands,
and a dedicated one-shot PIN unlock path.
This is an Android-handheld profile, not a generic policy for every ADB target.
Quest retains headset policy in ../quest; ChromeOS ARCVM,
emulators, TVs, watches, and automotive targets require their own lifecycle and
safety profiles. Neutral executable discovery, device enumeration, shell, and
power parsing live in ../../providers/adb.
Install Android SDK Platform Tools and authorize the controller's ADB RSA key
on the dedicated test device. When more than one eligible handheld can be
attached, set ANDROID_TESTBED_SERIAL in ignored private inventory or pass
--serial locally. ANDROID_SERIAL is accepted as the standard fallback.
For PIN unlock, install a JDK and Android SDK platform/build tools. The adapter builds the checked-in one-shot helper into the private state directory before opening the secret channel. No compiled helper, credential, serial, or signed application belongs in Git.
platforms/android/bin/android-device probe
platforms/android/bin/android-device doctor
platforms/android/bin/android-device statusThe common outer surface is:
bin/machine-control --target android target status
bin/machine-control --target android target doctor
bin/machine-control --target android target capabilities
bin/machine-control --target android target rebootConcrete target availability and selectors remain private inventory. When no private provider is active, the portable default can select exactly one authorized eligible handheld.
probe [--json] Stable read-only availability
status [--json] Boot, wake, user-storage, and keyguard state
doctor [--json] Human checks or machine-control-doctor/v0
serial Print the locally selected ADB serial
reboot [--timeout SECONDS] Full reboot, wait, and prove a new boot generation
wake Send Android's idempotent wake key
dismiss-keyguard Request ordinary keyguard dismissal
unlock [--stdin] [--json] Submit one PIN from its configured file or stdin
install PATH.apk Install or replace one explicit APK
launch PACKAGE Resolve and launch one explicit package
stop PACKAGE Force-stop one explicit package
screenshot OUTPUT Save one device-local display capture
logcat OUTPUT Save a bounded recent log snapshot
shell -- COMMAND [ARG...] Run one explicit ADB shell command
dismiss-keyguard only asks Android to dismiss the keyguard; a secure lock
screen still requires its credential. unlock is the protected operation.
Private inventory can declare a pin credential locator and expose its path
as ANDROID_TESTBED_PIN_FILE. The value belongs in an untracked controller-local
file, mode 0600, inside a caller-owned mode-0700 directory on POSIX. The
adapter requires an explicit device selector, rejects symlinks and unsafe or
nonregular files, and opens the secret only after unlock preflight. It accepts
one 4–16 digit PIN with an optional newline. Only the path enters the environment;
neither the path nor the credential appears in the unlock result.
With that locator configured, an agent can request unlock by target name:
bin/machine-control --target phone testbed -- unlock --jsonWithout a locator, unlock uses a hidden terminal prompt or dedicated stdin.
Use --stdin to explicitly override a configured file. Never put the PIN on the
command line:
platforms/android/bin/android-device unlock --stdin --jsonBefore opening a configured secret file or reading standard input, the adapter requires:
- one exact authorized physical handheld and a stable boot generation;
- completed boot and a secure PIN credential type;
- a visible PIN field discovered through UIAutomator;
- an observed zero failed-password wipe threshold; and
- a successfully built and staged one-shot helper.
When the legacy policy dump omits the threshold, a temporary read-only
shell-UID probe queries DevicePolicyManager for the exact foreground user.
Unknown, denied, changed-user, and nonzero results still refuse before the PIN
is read. UIAutomator discovery uses a mode-0600 temporary hierarchy, removed
in finally, and requires one known SystemUI password field with no text.
Non-secret ADB and build subprocesses receive no stdin; only explicit helper
delivery receives the credential bytes. Explicitly redirecting a private PIN file
into unlock --stdin therefore preserves it through preflight too.
The helper runs once as the already-authorized Android shell identity, reads 4 to 16 ASCII digits from standard input, injects digit and Enter key events in that process, emits no output, and clears its mutable buffer best effort. The host clears its buffer and removes the staged helper. The result reports only delivery, independently re-observed keyguard/user-storage effect, uncertainty, and zero retries. A failed or unknown outcome is never submitted again automatically.
This route does not clear or replace the credential, modify device policy, weaken lockout/biometrics, bypass ADB authorization, or support password and pattern credentials.
Current — live-tested, 2026-10-25: on a physical API-37 handheld, the common CLI adapter escape hatch unlocked a secure PIN keyguard using a private host file redirected into dedicated stdin. The corrected helper delivered once; keyguard and user-storage observations confirmed unlock, and a subsequent read-only doctor independently reported interaction unlocked. The PIN was never displayed or retained in evidence, and device-side temporary files were removed. A subsequent owner-reported reboot produced a changed boot generation, and the inventory-configured PIN file also unlocked it with one submission and zero retries. User storage was already unlocked before that attempt. This validates ordinary and post-reboot screen unlock with user storage available; first unlock from locked user storage and broader OEM coverage remain unqualified.
reboot waits for ADB reconnection, completed OS boot and a new boot generation.
It does not automatically unlock the screen. A configured controller-held PIN
remains available while the phone's credential-encrypted user storage is locked.
The unlock operation does not require that storage to be unlocked beforehand;
it can attempt first unlock once authorized ADB, native policy observation and
the known PIN surface are available. Successful effect requires both keyguard
and user storage to report unlocked afterward.
This route is unit-tested for initially locked user storage. Physical post-reboot unlock is accepted with user storage already available; first unlock from locked user storage still needs a separate physical test. Boot completion alone is not evidence that applications or user storage are ready.
Private controller state defaults to
~/.local/state/android-device-testbed (or the platform equivalent) and
contains only a local mutation lease and compiled helper cache. Override it
with ANDROID_TESTBED_STATE_DIR in private configuration.
Screenshots, logcat, shell output, applications, and UI state can contain private data. Keep artifacts local and review them before sharing. Common doctor output deliberately omits the serial, model, account/user names, controller paths, and configuration values.
cd platforms/android
python3 -m unittest discover -s tests -v
python3 -m compileall -q android_device.py tests ../../providers/adbCredential changes require helper build/start validation and refusal tests. Real PIN delivery requires a supervised dedicated test device and the correct credential; never add a wrong-PIN acceptance case.