ObliviOS Developer portal Project site

Home / Engineering notes / Grab detection

Grab detection engineering notes

Short, actionable lessons from authoring and reviewing the grab detection patches of ADR-169, for the next change to physical/grab-detection in oblivios-platform.

Short, actionable lessons from authoring and reviewing the grab detection patches of ADR-169, for the next change to physical/grab-detection in oblivios-platform. The design is 2026-10-15-grab-detection-design.md; the evidence rows are GRB-* in the validation matrix. Claims are labelled [verified-in-source], [measured] or [assumption].

  • lockNow() posts the lock; it does not lock. PhoneWindowManager.lockNow removes and posts mScreenLockTimeout and sets a pending flag, then returns [verified-in-source: services/core/.../policy/PhoneWindowManager.java:6068-6080]. A return without an exception therefore proves nothing about the keyguard. The 60-second timer is armed before the lock (init ignores a request while a timer runs), so the service cancels it when the keyguard has not shown five seconds later.
  • Register and unregister of a pointer listener are not symmetric. WindowManagerService.registerPointerEventListener does nothing when the display has no content, while PointerEventDispatcher.unregisterInputEventListener throws IllegalStateException for a listener that was never added [verified-in-source: services/core/.../wm/WindowManagerService.java:4087-4093, wm/PointerEventDispatcher.java:84-93]. A disarm must tolerate that, and a sensor registration returns a boolean that must be read.
  • Nothing may throw out of a service thread. An exception from onBootPhase is rethrown as RuntimeException("Failed to boot service …") [verified-in-source: services/core/.../SystemServiceManager.java:328-335]; an exception that leaves the service's own HandlerThread reaches the uncaught-exception handler of system_server [assumption]. Every entry point of the service is wrapped, and the cosmetic write (the triggered flag) is separated from the lock.
  • A shadow log must show what the rule rejected. The first detector returned nothing for a peak without recent touch, so the shadow phase could not answer the open question of a route without touch (design 4.2, 7). The detector now reports such a peak once per cool-down, marked untouched.
  • A release before the peak is void after a new touch. A finger that went up and is down again at the peak counted as pulled out of the fingers [measured: host harness, 2026-10-15, trigger=true released=true]. The detector clears the earlier release when a new touch starts.
  • Changing a return contract can hollow out old assertions. After the untouched-peak report, the assertion d != null no longer meant "a candidate", and the mutant "touch window is exclusive" survived [measured: mutate.py, 25 of 26 killed before the assertions checked touched]. Run the mutation check after every change of what a function returns.
  • Hidden Settings.Global keys are not readable by every app. SettingsProvider runs checkReadableAnnotation for a read of a hidden global key [verified-in-source: packages/SettingsProvider/.../SettingsProvider.java:2513,2640], so the keys of the feature are probably not an oracle for apps; the outcome is recorded by GRB-014 and stays [assumption] until then.
  • Put @hide on its own javadoc line, as the neighbouring keys do. A tag in the middle of a line may be missed by the API tooling and leak the key into the public API [assumption]; a module build does not catch that.
  • A module build proves little about the tests. m services SystemUI Settings passed (GRB-002) but does not compile tests/utils, so the broken BouncerMessageInteractorKosmos.kt fixture and any API check of the keys stay unproven. Patch 0008 adds the missing argument to the fixture; the full image build 2026101407 passed, but it does not compile tests/utils either, so the fixture is read against the constructor, not built.
  • Candidates in a row are at least about 3 s apart. The detector ignores peaks for the 2 s cooldown that follows a decision logged 1 s after the peak, so continuous shaking gives one candidate per 3.01 s [measured: lynx, 2026-10-17, GRB-004] and a counted series of pulls must leave 4 s between them.
  • A pull that stops is not a grab. Laying the phone down or catching it gave energy 0.62 to 1.15 m/s², below the 1.5 m/s² default [measured: GRB-004]; the test instruction "pull and keep moving" is what a thief does, and an instruction that ends the movement tests nothing.
  • A catch with a touching hand can trigger. In a series without touch, 6 of 7 trigger=true lines followed a peak without touch by 1.1 to 1.6 s with a release within 124 ms, so the catching hand reads as the touch of a second candidate [inference from timing; the touch events are not logged]. The counted series of 2026-10-18 repeats it: 6 of 10 pulls without touch locked the phone, each lock 1.10 to 1.36 s after a peak without touch, with a catch peak of 39.9 to 125.0 against 16.1 to 27.0 for the untouched pulls [measured: lynx, 2026-10-18, GRB-004]. The detector cannot tell the owner's catching hand from a thief's grab; whether a normal hand-over triggers is GRB-005.
  • A locked phone is dark to adb, and the log of the previous boot is not readable. The 60 s restart cannot be timed from the host: logcat -L is empty and pstore is denied. Read the lock from the init and GrabDetection lines before the restart, or use the owner's stopwatch [measured: GRB-008].
  • su <app uid> does not test what an app may do. settings and content fail first on INTERACT_ACROSS_USERS and ACCESS_CONTENT_PROVIDERS_EXTERNALLY, also for an ordinary key, so the refusal says nothing about the keys of the feature [measured]. GRB-014 needs a test app.
  • The stock lockdown text needs biometrics. PIN is required after lockdown is shown only when trust or biometrics are available [verified-in-source: BouncerMessageInteractor.kt, patch 0004]; with no fingerprint enrolled (dumpsys fingerprint, "count":0) the manual Lockdown shows nothing, and "no fingerprint offered" after a grab lock says nothing either. Enrol a fingerprint on the test phone before GRB-006 and GRB-012 are judged.
  • The 5 s keyguard check logs an error when the owner unlocks first. A PIN entered within 5 s of the lock gives E GrabDetection: keyguard did not show after the lock, cancelling the restart timer after the unlock, followed by on_device_unlocked: no started timer [measured: 2026-10-17 21:26:03]; harmless, but a false error line in the log.
  • The Settings screen does not observe the mode key. A screen that is open keeps the old switch state when the mode changes by adb [measured: GRB-013].
  • A raw recorder needs the screen on and untouched. An app in the background gets no continuous sensor events on Android 9 and later, so a recording stopped when the owner touched the screen and the app went away [measured: 2026-10-18, benign trace ended at its first touch]. dumpsys sensorservice keeps the last 50 accelerometer events but masks the values. tools/grab-recorder runs at 200 Hz; the service runs at SENSOR_DELAY_GAME, so a peak from the recorder is not a peak the service logs, and thresholds are set from the service's own log only.
  • Rest and a hand overlap in the movement level. One-second standard deviation of the magnitude: 0.005 to 0.01 on a table in the first 43 s, 0.018 to 0.43 over 360 s of the same table, 0.10 to 1.7 in a hand [measured: lynx, 2026-10-18]. A hold-state rule has no clean threshold (ADR-176).
  • Grabs that stand still fail only the energy condition. Eight staged grabs with the other hand became candidates and had energy 0.18 to 1.50 against 1.5 [measured: GRB-004, 2026-10-18]; the impact route of ADR-176 does not depend on what follows the peak.
  • The free fall before an impact separates a set-down from a grab; the peak does not. Grabs peak at 47 to 210 m/s², set-downs of 3 cm at 47 to 106 and hard ones at 83 to 199 [measured: GRB-019, 2026-10-25]. A phone set down falls freely for 16 to 163 ms before it lands (magnitude below 4 m/s²) and none of 12 staged grabs has any [measured: the real GrabDetector replayed over the recordings at 50 Hz in five phases of the sample grid, 2026-10-26]; ADR-195 uses it. The detector must see the free fall at the service's own rate: a fall of 3 cm is 4 samples at 50 Hz, and one run of samples counts as k intervals, not k - 1. The free-fall tracker has to update before the cool-down check, or a fall that ends inside a cool-down is lost.
  • Hold the test to the real code, not a model of it. A first Python model of the rule counted only the last low run within 100 ms of the impact and reported no free fall for nine of eleven hard set-downs; replaying the Java class over the recordings gave the right answer. Replay the real class over the recordings before a threshold is chosen. A mutation run whose base test fails reports every mutant as killed; mutate.py is meaningful only after run.sh prints all passed.
  • The recordings differ in rate. grab-still.csv was recorded at 40 Hz and the others at 238 Hz; a replay resamples every file to 20 ms steps. The recordings stay on the phone and the workstation and are not committed.
  • The first device look at the free-fall rule found a gap on each side [measured: GRB-020, GRB-021, lynx 2026102302, 2026-10-27, shadow mode, level 1]. Of 21 set-downs 20 gave a free fall of 19 to 208 ms and no lock; one soft set-down gave fallMs=0 and would lock. Of 7 recorded grabs 6 gave fallMs=0 and would lock; one gave 16 ms and would not. A drop from 30 cm gave 154 to 196 ms and no lock (0 of 5). The longest hard set-down (208 ms) is 42 ms under the limit. The result stands on one hand and one phone; the number of pulls was not counted, so pulls under 30 m/s² are unseen.
  • A grab and a pickup look the same at the first sample, and only the width of the pulse tells them apart [measured: GRB-024, 2026-10-29]. The impact line shows the first sample over impactPeak, not the peak of the pulse: the 12 recorded grabs give 30 to 50 m/s² there and a pickup from a table 30.4, with no free fall in both. The recordings give the width, the time above 15 m/s²: 171 to 310 ms for a grab, 4 to 13 ms for the spikes of pickups and bumps. The rule is in ADR-204 (minPulseMs, 120 ms). Shadow mode ran the same code as active mode and was right about every event it saw; it saw only staged ones, and the first normal pickup in active mode locked the phone. A shadow measurement of staged events is not a test of daily use: pick the phone up from a table, put it in a pocket and take it out, in a block of its own, and count the impact lines. The recordings stay on the phone (/sdcard/Android/data/org.freehold.grabrec/files, 7 files, 23 MB) and are pulled with adb pull into a scratch directory; tools/grab-recorder/replay replays the real detector over them. Do not ask the owner to repeat a measurement before the recordings and the earlier rows are read: they hold 12 grabs, 17 set-downs of 3 cm, 11 hard set-downs, one pickup and some bumps.
  • Shadow mode logs the same impact line as active mode (locks=, fallMs, level, mode=1), so a set of grabs can be measured without ten PIN entries; the first block of the session ran in mode 2 and locked at 11:46:07 and 11:46:15 with fallMs=0.
  • Shadow and active mode decide the same, and the pickup and the levels were shown [verified-in-source: GrabDetectionService.onDecision, patches 0003 and 0009; measured: GRB-018 to GRB-024, lynx 2026110203, 2026-11-03]. Only the call lockAndArmRestart depends on the mode; the locks= of a shadow line is what active mode does. Active run (owner's reports against the log): a pickup 5 impact lines all locks=false; set-downs 14 lines locks=false; one hard set-down with the hand still on the phone gave peak=156.6 fallMs=0 pulseMs=134 locks=true and locked (the signature of a grab: no free fall, a pulse of 130 to 150 ms); 4 grabs locks=true, each followed by disarmed and auto_reboot: started timer for 60 seconds. Shadow run at the standard level: pickup 0 of 10 locks (a line with fallMs=0 pulseMs=34 is the case of frameworks-base/0011), drops 50 cm 4 of 5 (fallMs 284 to 356; the miss was 243, limit 250) and 1 m 5 of 5, set-downs 0 of 18, grabs 7 of 10 (the gentle ones stay under the 30 m/s^2 first-sample limit and make no line; the owner leaves that as it is). Level 0 locks set-downs, level 2 only grabs of 60 m/s^2 and more. The pulse limit lies between 102 ms (locks=false) and 130 ms.
  • A switch to a user without a lock screen cancels the restart timer [measured: GRB-017, lynx 2026110203, 2026-11-03]: after a grab lock the owner switched from the lock screen to a second user; the log shows sendContinueUserSwitchLU-0-to-13 and one second later auto_reboot: on_device_unlocked: stopped timer; the phone then ran on the normal 18 hour timer. Fix: ADR-213, no user switcher on any locked device. To test it: pm create-user NAME (the removal by the owner, pm remove-user ID, destroys the CE and DE keys of the id through vold), mode 2, a pull, the switcher on the PIN screen. While a screen is off the service is disarmed (the keyguard shows), so drops made then are not logged: a block of drops that gave no line was repeated after the unlock.

Read from docs/architecture/grab-detection-engineering-notes.md.