- Kotlin 98.6%
- PowerShell 1.4%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
SignalScheduler: the loop tick now owns the on-to-off transition. turnOn used to arm a one-shot off at the same instant, so the one-shot won, the tick found a dark torch and relit it immediately - calls showed a continuous glow instead of a blink. The dark half of the call loop now uses the same user-set time as the light half; the UI field is 'Light on / off' and CALL_OFF_MS is gone. Buzzer: tag the vibration as USAGE_ALARM. The untagged call is TOUCH-class, and this device has touch vibration off, so the system silently ignored every buzz. Docs (PLAN, README, AGENTS) updated, decision log appended. versionCode 2, versionName 0.1.1. |
||
| app | ||
| gradle | ||
| scripts | ||
| .gitattributes | ||
| .gitignore | ||
| AGENTS.md | ||
| build.gradle.kts | ||
| gradle.properties | ||
| gradlew | ||
| gradlew.bat | ||
| LICENSE | ||
| PLAN.md | ||
| README.md | ||
| settings.gradle.kts | ||
FaceDown
A personal Android app for a Pixel 10 Pro XL on Android 17: the phone goes silent when you place it face down, tells you about incoming calls with the dimmest possible LED blink instead of sound, and returns to normal when you pick it up and unlock it.
It replaces three MacroDroid macros that could not do this reliably (see PLAN.md §2).
Status: working, personal use. Builds, unit tests pass, and it has been run on a Pixel 10 Pro XL (Android 17) with the behaviour below checked by hand. Debug APK only, sideloaded — see
PLAN.md§12 for the exact verification ladder.
What it does
- Face down → night mode. After 1.2 s face down, Do Not Disturb switches to alarms only and one short blink confirms it.
- Incoming call while face down. The LED blinks in a loop — on for the configured time, dark for the same time — with a short buzz, until the call ends.
- Pickup → normal. Lift the phone (or unlock it) and Do Not Disturb is restored, but only if this app turned it on.
- Sleep hours. Between the configured hours a pickup keeps it silent and nothing blinks; only an unlock ends night mode, so a 3 a.m. glance does not un-mute the phone.
- Safety nets. Stopping the service always restores DND, a leftover armed DND is cleaned up on the next start, and 12 h face down restores it without an unlock.
Calls only — no message or app notifications.
Requirements
- JDK 21 and Android SDK 37.0.
scripts\env.ps1points at installs under%LOCALAPPDATA%\Androidand exportsJAVA_HOME,ANDROID_HOMEandPATHfor the shell.
. .\scripts\env.ps1
Build
.\gradlew.bat assembleDebug # app\build\outputs\apk\debug\app-debug.apk
.\gradlew.bat testDebugUnitTest # detector state-machine tests
The wrapper pins Gradle 9.9.1. If the project is checked out under a non-ASCII path, AGP refuses
to build it, so android.overridePathCheck=true is set in gradle.properties.
Install
adb install -r app\build\outputs\apk\debug\app-debug.apk
Or download the latest APK from Releases. The release build is minified (~2 MB) and signed with a debug key, so it installs like any sideloaded app.
First run on the phone
The app shows a "Setup needed" card until these are granted:
- Notifications — shows the foreground-service notification.
- Do Not Disturb access — opens the system special-access screen.
- Phone state — lets the app see the
RINGINGcall state (no caller identity is read). - Battery: unrestricted — otherwise Doze stops sensor delivery after ~30–60 min.
Also "Flip to Shhh" (Digital Wellbeing) does the same DND-on-face-down trick. It is not installed on this phone (verified 2026-11-17), so there is nothing to turn off — but leave it disabled if it ever appears, or two systems will fight over DND.
Testing
Build-level checks are done; device behaviour is verified by hand. The checklist — what to
do, what to expect, and what to report back — lives in PLAN.md §12 "Physical test checklist".
To see what the app actually did:
adb logcat -d -s FaceDown
Permissions
| Permission | Why |
|---|---|
FOREGROUND_SERVICE_SPECIAL_USE |
Continuous sensor access; background apps get none |
POST_NOTIFICATIONS (runtime) |
The foreground-service notification — required by Android, MIN importance (silent, no status icon). Blocking it does not stop the service. |
READ_PHONE_STATE (runtime) |
Detect the incoming-call state |
VIBRATE |
Call alert buzz |
WAKE_LOCK |
Accurate blink timing |
RECEIVE_BOOT_COMPLETED |
Restart the watcher after reboot |
REQUEST_IGNORE_BATTERY_OPTIMIZATIONS |
Survive Doze |
| Do Not Disturb access (special) | Switch DND to alarms-only and back |
No camera permission (the torch API needs none), no notification listener, no accessibility service, no internet permission.
Project layout
app/src/main/java/nl/samueldebruin/facedown/
MainActivity.kt permissions snapshot + Compose host
ui/ dark theme, single screen, permission helpers
core/FaceDownDetector.kt pure DAY/NIGHT state machine (unit-tested)
data/Settings.kt SharedPreferences-backed settings
data/AppState.kt service ⇄ UI state
dnd/DndController.kt arms/restores DND, never touches a DND it did not set
signal/TorchDriver.kt dimmest torch level, hardware-state tracking
signal/SignalScheduler.kt the only owner of the torch (pulse + loop + watchdog)
signal/Buzzer.kt call-alert vibration
calls/CallWatcher.kt TelephonyCallback, RINGING only
service/FaceDownService.kt the foreground service
service/BootReceiver.kt restart on boot
app/src/test/java/... FaceDownDetector tests (9)
Documents
| File | Purpose |
|---|---|
PLAN.md |
Behaviour, settings, architecture, platform facts, limitations, milestones |
AGENTS.md |
What a future change must preserve; working rules for this repo |
Not planned
Play Store distribution, root/Shizuku, accessibility or notification-listener hacks,
notification patterns for anything other than calls, a global three-finger-swipe screenshot
(Android does not allow it without a touch-hijacking service — see PLAN.md §13), and any
network or analytics component.
License
MIT — see LICENSE.