Wake up faster, more reliably

Author: tstromberg

README.md

@@ -18,27 +18,50 @@ While initially designed for an Android-based home security system, it's also pe
 
 ## Features
 
-- Camera motion detection with adjustable sensitivity
-- Ambient light sensor for detecting lighting changes
-- Auto-unlock screen and launch your dashboard app
-- Automatic keyguard dismissal (works with swipe-to-unlock and no security)
-- **App preload for instant startup** - Optional background preloading for near-instant app appearance
-- Configurable notification sound on wake
-- Start at boot for set-and-forget operation
-- **Optimized for low-end devices** - Intelligent memory management and frame throttling
-- Zero-animation instant transitions for snappy responsiveness
-- Clean, simple UI with tablet layouts
-- Full accessibility support with TalkBack
+- **Motion detection** - Detects when you walk up using the camera or light sensor
+- **Automatic unlock** - Wakes up and unlocks your device (works with swipe-to-unlock or no lock screen security)
+- **Launch your favorite app** - Automatically opens your chosen app (Home Assistant, calendar, transit schedule, etc.)
+- **Fast startup** - Optional instant app loading so your app appears immediately
+- **Notification sound** - Optional sound to let you know the device has woken up
+- **Automatic start** - Starts working when you turn on your device, no need to open the app
+- **Works on budget devices** - Runs smoothly even on cheap tablets with limited memory
+- **Clean and simple** - Easy-to-use interface that works on both phones and tablets
+- **Accessibility support** - Works with TalkBack for vision-impaired users
 
-## Permissions
+## Installation
 
-On first launch, the app will request the following permissions:
+1. Download the latest APK file from the [Releases](../../releases) page
+2. On your Android device, open the downloaded APK file
+3. If prompted, allow installation from unknown sources
+4. Tap "Install"
+5. Once installed, open The Observer Effect and follow the setup prompts
 
-- **Camera** - For motion detection
-- **Display over other apps** (SYSTEM_ALERT_WINDOW) - Required to reliably launch apps from background on Android 10+
-- **Battery optimization exemption** - For reliable background operation
+**Requires Android 8.0 or newer**
 
-These permissions are essential for the app to function properly.
+## Getting Started
+
+The Observer Effect is designed to be simple to use, even if you're not a technical user. Just install the app and follow the on-screen prompts.
+
+### Permissions
+
+**The app will automatically prompt you for the following permissions when you first launch it:**
+
+- **Camera** - Allows the app to detect when you approach the device
+- **Display over other apps** - Lets the app wake up your device and launch your chosen app
+- **Battery optimization exemption** - Keeps the app running in the background so it can detect your presence
+
+Simply tap "Allow" or "Grant" when prompted. These permissions are required for the app to work.
+
+### Important: Background Management (Low-End Devices)
+
+**If you have a budget tablet or low-end Android device**, you may need to manually allow the app to run in the background without being killed by the system. Without this setting, the app won't be able to detect your presence when the screen is off.
+
+**How to allow background operation:**
+
+- **AllWinner tablets**: Go to **Settings → Background Manage** and add The Observer Effect to the allowed apps list
+- **Other devices**: Look for settings like "Battery Management", "App Battery Saver", "Background Apps", or "Protected Apps" in your device settings and ensure The Observer Effect is allowed to run in the background
+
+If you're not sure where to find this setting, search your device settings for "background" or "battery optimization" and look for The Observer Effect in the list.
 
 ## Performance
 
@@ -60,7 +83,11 @@ The Observer Effect is optimized to run on a wide range of devices, from high-en
 - Disable app preload to save memory
 - Choose simple launch apps (launchers, calendars) over browsers
 
-## Building
+---
+
+## For Developers
+
+### Building from Source
 
 You are probably best off using Android Studio, but we have make targets too:
 
@@ -70,7 +97,7 @@ make release      # Build release APK → out/observer-effect-release.apk
 make sideload     # Install via adb
 ```
 
-**Requirements:** Android 8.0+, JDK 17+
+**Requirements:** JDK 17+
 
 ## License
 

app/src/main/AndroidManifest.xml

@@ -7,6 +7,7 @@
     <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
     <uses-permission android:name="android.permission.REQUEST_IGNORE_BATTERY_OPTIMIZATIONS" />
     <uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW" />
+    <uses-permission android:name="android.permission.WAKE_LOCK" />
 
     <uses-feature android:name="android.hardware.camera" android:required="false" />
     <uses-feature android:name="android.hardware.sensor.light" android:required="false" />

app/src/main/kotlin/com/observer/effect/LauncherActivity.kt

@@ -8,6 +8,7 @@ import android.os.Build
 import android.os.Bundle
 import android.os.Handler
 import android.os.Looper
+import android.os.PowerManager
 import android.util.Log
 import android.view.WindowManager
 
@@ -33,6 +34,16 @@ class LauncherActivity : Activity() {
         // This prevents hanging if target app never comes to foreground
         timeoutHandler.postDelayed(timeoutRunnable, FINISH_TIMEOUT_MS)
 
+        // Acquire a wake lock to ensure the screen turns on reliably
+        // This is more robust than just relying on window flags
+        val powerManager = getSystemService(Context.POWER_SERVICE) as PowerManager
+        val wakeLock =
+            powerManager.newWakeLock(
+                PowerManager.SCREEN_BRIGHT_WAKE_LOCK or PowerManager.ACQUIRE_CAUSES_WAKEUP,
+                "ObserverEffect:LauncherWakeLock",
+            )
+        wakeLock.acquire(1 * 1000L /* 1 second */)
+
         val targetPackage = intent.getStringExtra(EXTRA_TARGET_PACKAGE)
         Log.i(TAG, "LauncherActivity started for package: $targetPackage (API ${Build.VERSION.SDK_INT})")
 
@@ -52,25 +63,36 @@ class LauncherActivity : Activity() {
             // Request keyguard dismissal
             val keyguardManager = getSystemService(Context.KEYGUARD_SERVICE) as? KeyguardManager
             if (keyguardManager != null) {
-                keyguardManager.requestDismissKeyguard(
-                    this,
-                    object : KeyguardManager.KeyguardDismissCallback() {
-                        override fun onDismissSucceeded() {
-                            Log.i(TAG, "Keyguard dismissed successfully")
-                            launchTargetApp()
-                        }
-
-                        override fun onDismissError() {
-                            Log.e(TAG, "Keyguard dismiss error")
-                            launchTargetApp()
-                        }
-
-                        override fun onDismissCancelled() {
-                            Log.w(TAG, "Keyguard dismiss cancelled")
-                            finish()
-                        }
-                    },
-                )
+                // Check if keyguard is actually locked
+                val isKeyguardLocked = keyguardManager.isKeyguardLocked
+                Log.d(TAG, "Keyguard locked state: $isKeyguardLocked")
+
+                if (isKeyguardLocked) {
+                    // Only request dismissal if keyguard is actually shown
+                    keyguardManager.requestDismissKeyguard(
+                        this,
+                        object : KeyguardManager.KeyguardDismissCallback() {
+                            override fun onDismissSucceeded() {
+                                Log.i(TAG, "Keyguard dismissed successfully")
+                                launchTargetApp()
+                            }
+
+                            override fun onDismissError() {
+                                Log.e(TAG, "Keyguard dismiss error")
+                                launchTargetApp()
+                            }
+
+                            override fun onDismissCancelled() {
+                                Log.w(TAG, "Keyguard dismiss cancelled")
+                                finish()
+                            }
+                        },
+                    )
+                } else {
+                    // Keyguard not locked, launch app immediately
+                    Log.d(TAG, "Keyguard not locked, launching app immediately")
+                    launchTargetApp()
+                }
             } else {
                 Log.e(TAG, "KeyguardManager not available, launching app anyway")
                 launchTargetApp()

app/src/main/kotlin/com/observer/effect/MainActivity.kt

@@ -93,10 +93,6 @@ class MainActivity : AppCompatActivity() {
         val notificationSound = prefs.getString(KEY_NOTIFICATION_SOUND, "") ?: ""
 
         with(binding) {
-            // Set build type indicator
-            val isDebug = (applicationInfo.flags and ApplicationInfo.FLAG_DEBUGGABLE) != 0
-            buildTypeIndicator?.text = if (isDebug) "[D]" else "[R]"
-
             // Setup camera spinner
             val cameraOptions =
                 arrayOf(