Add command_screen_off to turn the display off while the device stays awake

app/src/main/AndroidManifest.xml

@@ -377,6 +377,29 @@
             </intent-filter>
         </receiver>
 
+        <!--Device admin holding only the force lock policy, used by the command_screen_off
+        notification command to turn the display off (see ScreenOffHelper).-->
+        <receiver
+            android:name=".util.ScreenOffAdminReceiver"
+            android:description="@string/screen_off_admin_description"
+            android:exported="true"
+            android:label="@string/screen_off_admin_name"
+            android:permission="android.permission.BIND_DEVICE_ADMIN">
+            <meta-data
+                android:name="android.app.device_admin"
+                android:resource="@xml/screen_off_device_admin" />
+            <intent-filter>
+                <action android:name="android.app.action.DEVICE_ADMIN_ENABLED" />
+            </intent-filter>
+        </receiver>
+
+        <!--Transparent activity that opens the device admin activation screen for the
+        command_screen_off notification command (see ScreenOffAdminRequestActivity).-->
+        <activity
+            android:name=".util.ScreenOffAdminRequestActivity"
+            android:exported="false"
+            android:theme="@android:style/Theme.Translucent.NoTitleBar" />
+
         <activity android:name=".launch.link.LinkActivity"
             android:exported="true"
             android:launchMode="singleTask">

app/src/main/kotlin/io/homeassistant/companion/android/notifications/MessagingManager.kt

@@ -96,6 +96,8 @@ import io.homeassistant.companion.android.settings.assist.AssistConfigManager
 import io.homeassistant.companion.android.settings.assist.DefaultAssistantManager
 import io.homeassistant.companion.android.util.FlashlightHelper
 import io.homeassistant.companion.android.util.PermissionRequestMediator
+import io.homeassistant.companion.android.util.ScreenOffAdminRequestActivity
+import io.homeassistant.companion.android.util.ScreenOffHelper
 import io.homeassistant.companion.android.util.UrlUtil
 import io.homeassistant.companion.android.util.sensitive
 import io.homeassistant.companion.android.vehicle.HaCarAppService
@@ -131,6 +133,7 @@ class MessagingManager @Inject constructor(
     private val settingsDao: SettingsDao,
     private val textToSpeechClient: TextToSpeechClient,
     private val flashlightHelper: FlashlightHelper,
+    private val screenOffHelper: ScreenOffHelper,
     private val permissionRequestMediator: PermissionRequestMediator,
     private val assistConfigManager: AssistConfigManager,
     private val defaultAssistantManager: DefaultAssistantManager,
@@ -186,6 +189,7 @@ class MessagingManager @Inject constructor(
         const val COMMAND_VOLUME_LEVEL = "command_volume_level"
         const val COMMAND_BLUETOOTH = "command_bluetooth"
         const val COMMAND_SCREEN_ON = "command_screen_on"
+        const val COMMAND_SCREEN_OFF = "command_screen_off"
         const val COMMAND_MEDIA = "command_media"
         const val COMMAND_HIGH_ACCURACY_MODE = "command_high_accuracy_mode"
         const val COMMAND_ACTIVITY = "command_activity"
@@ -247,6 +251,7 @@ class MessagingManager @Inject constructor(
             COMMAND_ACTIVITY,
             COMMAND_WEBVIEW,
             COMMAND_SCREEN_ON,
+            COMMAND_SCREEN_OFF,
             COMMAND_MEDIA,
             DeviceCommandData.COMMAND_UPDATE_SENSORS,
             COMMAND_LAUNCH_APP,
@@ -543,7 +548,7 @@ class MessagingManager @Inject constructor(
                             handleDeviceCommands(jsonData)
                         }
 
-                        COMMAND_SCREEN_ON -> {
+                        COMMAND_SCREEN_ON, COMMAND_SCREEN_OFF -> {
                             handleDeviceCommands(jsonData)
                         }
 
@@ -838,9 +843,20 @@ class MessagingManager @Inject constructor(
                     "HomeAssistant::NotificationScreenOnWakeLock",
                 )
                 wakeLock?.acquire(1 * 30 * 1000L) // 30 seconds
+                // Released while the wake lock is held so the device cannot suspend meanwhile
+                screenOffHelper.turnScreenOn()
                 wakeLock?.release()
             }
 
+            COMMAND_SCREEN_OFF -> {
+                if (!screenOffHelper.canTurnScreenOff()) {
+                    notifyMissingPermission(type = message, serverId = serverId)
+                } else if (!screenOffHelper.turnScreenOff()) {
+                    Timber.d("Unable to turn the screen off, posting notification to device")
+                    sendNotification(data)
+                }
+            }
+
             COMMAND_MEDIA -> {
                 if (!NotificationManagerCompat.getEnabledListenerPackages(context)
                         .contains(context.packageName)
@@ -1801,6 +1817,13 @@ class MessagingManager @Inject constructor(
         context.startActivity(intent)
     }
 
+    private fun requestDeviceAdminPermission() {
+        // The activation screen only opens from an activity, see ScreenOffAdminRequestActivity
+        val intent = Intent(context, ScreenOffAdminRequestActivity::class.java)
+        intent.flags = Intent.FLAG_ACTIVITY_NEW_TASK
+        context.startActivity(intent)
+    }
+
     private fun requestNotificationPermission() {
         val intent = Intent(Settings.ACTION_NOTIFICATION_LISTENER_SETTINGS)
         intent.flags = Intent.FLAG_ACTIVITY_NEW_TASK
@@ -2130,6 +2153,8 @@ class MessagingManager @Inject constructor(
                         when (type) {
                             COMMAND_WEBVIEW, COMMAND_ACTIVITY, COMMAND_LAUNCH_APP -> requestSystemAlertPermission()
 
+                            COMMAND_SCREEN_OFF -> requestDeviceAdminPermission()
+
                             COMMAND_RINGER_MODE, COMMAND_DND, COMMAND_VOLUME_LEVEL -> requestDNDPermission()
 
                             COMMAND_MEDIA -> requestNotificationPermission()

app/src/main/kotlin/io/homeassistant/companion/android/util/ScreenOffAdminReceiver.kt

@@ -0,0 +1,20 @@
+package io.homeassistant.companion.android.util
+
+import android.app.admin.DeviceAdminReceiver
+import android.content.Context
+import android.content.Intent
+import dagger.hilt.android.AndroidEntryPoint
+import javax.inject.Inject
+
+/** Device admin holding the force lock policy so [ScreenOffHelper] can cut the display power. */
+@AndroidEntryPoint
+class ScreenOffAdminReceiver : DeviceAdminReceiver() {
+
+    @Inject
+    lateinit var screenOffHelper: ScreenOffHelper
+
+    // Without this the wake lock held while the screen was off would never be released
+    override fun onDisabled(context: Context, intent: Intent) {
+        screenOffHelper.turnScreenOn()
+    }
+}

app/src/main/kotlin/io/homeassistant/companion/android/util/ScreenOffAdminRequestActivity.kt

@@ -0,0 +1,44 @@
+package io.homeassistant.companion.android.util
+
+import android.app.admin.DevicePolicyManager
+import android.content.ActivityNotFoundException
+import android.content.ComponentName
+import android.content.Intent
+import android.os.Bundle
+import androidx.activity.ComponentActivity
+import androidx.activity.result.contract.ActivityResultContracts
+import io.homeassistant.companion.android.common.R as commonR
+import timber.log.Timber
+
+/**
+ * Opens the system screen to activate [ScreenOffAdminReceiver] as device admin. Routed through
+ * this transparent activity since some manufacturers, like Samsung, refuse to open that screen
+ * from a new task, which is the only way the notification handling can start an activity.
+ */
+class ScreenOffAdminRequestActivity : ComponentActivity() {
+
+    private val requestAdmin =
+        registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { finish() }
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        if (savedInstanceState != null) return
+
+        val intent = Intent(DevicePolicyManager.ACTION_ADD_DEVICE_ADMIN)
+            .putExtra(
+                DevicePolicyManager.EXTRA_DEVICE_ADMIN,
+                ComponentName(this, ScreenOffAdminReceiver::class.java),
+            )
+            .putExtra(
+                DevicePolicyManager.EXTRA_ADD_EXPLANATION,
+                getString(commonR.string.screen_off_admin_description),
+            )
+        try {
+            requestAdmin.launch(intent)
+        } catch (e: ActivityNotFoundException) {
+            // Some devices, like Android Automotive, have no device admin settings
+            Timber.w(e, "Unable to open the device admin activation screen")
+            finish()
+        }
+    }
+}

app/src/main/kotlin/io/homeassistant/companion/android/util/ScreenOffHelper.kt

@@ -0,0 +1,78 @@
+package io.homeassistant.companion.android.util
+
+import android.annotation.SuppressLint
+import android.app.KeyguardManager
+import android.app.admin.DevicePolicyManager
+import android.content.ComponentName
+import android.content.Context
+import android.os.PowerManager
+import androidx.annotation.VisibleForTesting
+import androidx.core.content.getSystemService
+import dagger.hilt.android.qualifiers.ApplicationContext
+import javax.inject.Inject
+import javax.inject.Singleton
+import timber.log.Timber
+
+private const val SCREEN_OFF_WAKE_LOCK_TAG = "HomeAssistant::NotificationScreenOffWakeLock"
+
+/**
+ * Cuts the display power with [DevicePolicyManager.lockNow] while a partial wake lock keeps the
+ * device awake. Requires [ScreenOffAdminReceiver] active as device admin and no secure keyguard.
+ * All functions must be called from the main thread, the wake lock state is not synchronized.
+ */
+@Singleton
+class ScreenOffHelper @Inject constructor(@ApplicationContext private val context: Context) {
+
+    private val devicePolicyManager by lazy { context.getSystemService<DevicePolicyManager>() }
+    private val keyguardManager by lazy { context.getSystemService<KeyguardManager>() }
+    private val powerManager by lazy { context.getSystemService<PowerManager>() }
+    private val adminComponent by lazy { ComponentName(context, ScreenOffAdminReceiver::class.java) }
+
+    private var screenOffWakeLock: PowerManager.WakeLock? = null
+
+    /** Whether the screen is currently turned off by [turnScreenOff]. */
+    @VisibleForTesting
+    internal val isScreenOff: Boolean
+        get() = screenOffWakeLock != null
+
+    /** Whether [ScreenOffAdminReceiver] is active as device admin so [turnScreenOff] can be used. */
+    fun canTurnScreenOff(): Boolean = devicePolicyManager?.isAdminActive(adminComponent) == true
+
+    /**
+     * @return `true` if the screen was turned off, `false` when the device admin is not active or
+     * a secure keyguard is set
+     */
+    // The wake lock is held until the screen is turned back on, no timeout would be safe
+    @SuppressLint("WakelockTimeout")
+    fun turnScreenOff(): Boolean {
+        val devicePolicyManager = devicePolicyManager ?: return false
+        if (keyguardManager?.isDeviceSecure != false) {
+            Timber.w("Not turning the screen off, the secure keyguard would lock the device")
+            return false
+        }
+        return try {
+            if (screenOffWakeLock == null) {
+                // Keep the CPU and network awake so the device stays reachable by the server
+                screenOffWakeLock = powerManager
+                    ?.newWakeLock(PowerManager.PARTIAL_WAKE_LOCK, SCREEN_OFF_WAKE_LOCK_TAG)
+                    ?.apply { acquire() }
+            }
+            devicePolicyManager.lockNow()
+            true
+        } catch (e: SecurityException) {
+            Timber.e(e, "Device admin is not active, cannot turn the screen off")
+            turnScreenOn()
+            false
+        }
+    }
+
+    /** @return `true` if the screen was turned off before, `false` if there was nothing to do */
+    fun turnScreenOn(): Boolean {
+        val wakeLock = screenOffWakeLock ?: return false
+        screenOffWakeLock = null
+        if (wakeLock.isHeld) {
+            wakeLock.release()
+        }
+        return true
+    }
+}

app/src/main/res/xml/changelog_master.xml

@@ -3,6 +3,7 @@
     tools:ignore="MissingDefaultResource">
     <release version="2026.7.2 - Main" versioncode="3">
         <change>Android 17: added assistant volume level sensor + notification command for control</change>
+        <change>New notification command command_screen_off to turn the screen off while the device stays awake and connected (requires activating the device admin), command_screen_on turns it back on</change>
         <change>Bug fixes and dependency updates</change>
     </release>
     <release version="2026.7.2 - Wear" versioncode="2">
@@ -11,6 +12,7 @@
     </release>
     <release version="2026.7.2 - Automotive" versioncode="1">
         <change>Android 17: added assistant volume level sensor + notification command for control</change>
+        <change>New notification command command_screen_off to turn the screen off while the device stays awake and connected (requires activating the device admin), command_screen_on turns it back on</change>
         <change>Bug fixes and dependency updates</change>
     </release>
 </changelog>

app/src/main/res/xml/screen_off_device_admin.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="utf-8"?>
+<device-admin xmlns:android="http://schemas.android.com/apk/res/android">
+    <uses-policies>
+        <force-lock />
+    </uses-policies>
+</device-admin>

app/src/test/kotlin/io/homeassistant/companion/android/notifications/MessagingManagerScreenCommandsTest.kt

@@ -0,0 +1,115 @@
+package io.homeassistant.companion.android.notifications
+
+import android.app.ActivityManager
+import android.app.Application
+import android.os.Looper
+import android.os.Process
+import androidx.test.core.app.ApplicationProvider
+import dagger.hilt.android.testing.HiltTestApplication
+import io.homeassistant.companion.android.common.data.integration.IntegrationRepository
+import io.homeassistant.companion.android.common.data.servers.ServerManager
+import io.homeassistant.companion.android.common.notifications.NotificationData
+import io.homeassistant.companion.android.database.server.Server
+import io.homeassistant.companion.android.util.ScreenOffAdminRequestActivity
+import io.homeassistant.companion.android.util.ScreenOffHelper
+import io.mockk.coEvery
+import io.mockk.every
+import io.mockk.mockk
+import io.mockk.verify
+import org.junit.Assert.assertEquals
+import org.junit.Before
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+import org.robolectric.Shadows.shadowOf
+import org.robolectric.annotation.Config
+
+/**
+ * Covers the routing of the screen on and screen off commands only, [MessagingManager] has no
+ * further coverage yet.
+ */
+@RunWith(RobolectricTestRunner::class)
+@Config(application = HiltTestApplication::class)
+class MessagingManagerScreenCommandsTest {
+
+    private lateinit var screenOffHelper: ScreenOffHelper
+    private lateinit var messagingManager: MessagingManager
+
+    @Before
+    fun setUp() {
+        val serverManager = mockk<ServerManager>(relaxed = true)
+        val integrationRepository = mockk<IntegrationRepository>(relaxed = true)
+        coEvery { serverManager.getServer(any<Int>()) } returns mockk<Server>(relaxed = true)
+        coEvery { serverManager.integrationRepository(any()) } returns integrationRepository
+        coEvery { integrationRepository.isTrusted() } returns true
+        screenOffHelper = mockk(relaxed = true)
+
+        messagingManager = MessagingManager(
+            context = ApplicationProvider.getApplicationContext<Application>(),
+            okHttpClientProvider = mockk(relaxed = true),
+            serverManager = serverManager,
+            prefsRepository = mockk(relaxed = true),
+            notificationDao = mockk(relaxed = true),
+            sensorRepository = mockk(relaxed = true),
+            settingsDao = mockk(relaxed = true),
+            textToSpeechClient = mockk(relaxed = true),
+            flashlightHelper = mockk(relaxed = true),
+            screenOffHelper = screenOffHelper,
+            permissionRequestMediator = mockk(relaxed = true),
+            assistConfigManager = mockk(relaxed = true),
+            defaultAssistantManager = mockk(relaxed = true),
+            bluetoothSensorManager = mockk(relaxed = true),
+        )
+    }
+
+    private fun handleMessage(message: String) {
+        messagingManager.handleMessage(mapOf(NotificationData.MESSAGE to message), "FCM")
+        // handleMessage launches on the main dispatcher, run the enqueued work before verifying
+        shadowOf(Looper.getMainLooper()).idle()
+    }
+
+    @Test
+    fun `Given screen off is possible when receiving screen off command then the screen is turned off`() {
+        every { screenOffHelper.canTurnScreenOff() } returns true
+        every { screenOffHelper.turnScreenOff() } returns true
+
+        handleMessage(MessagingManager.COMMAND_SCREEN_OFF)
+
+        verify(exactly = 1) { screenOffHelper.turnScreenOff() }
+    }
+
+    @Test
+    fun `Given screen off is not possible when receiving screen off command then the screen is not turned off`() {
+        every { screenOffHelper.canTurnScreenOff() } returns false
+
+        handleMessage(MessagingManager.COMMAND_SCREEN_OFF)
+
+        verify(exactly = 0) { screenOffHelper.turnScreenOff() }
+    }
+
+    @Test
+    fun `Given screen was turned off when receiving screen on command then the screen is turned back on`() {
+        handleMessage(MessagingManager.COMMAND_SCREEN_ON)
+
+        verify(exactly = 1) { screenOffHelper.turnScreenOn() }
+    }
+
+    @Test
+    fun `Given the app in the foreground when screen off is not possible then the device admin activation is opened`() {
+        every { screenOffHelper.canTurnScreenOff() } returns false
+        val application = ApplicationProvider.getApplicationContext<Application>()
+        val processInfo = ActivityManager.RunningAppProcessInfo(
+            application.applicationInfo.processName,
+            Process.myPid(),
+            null,
+        ).apply { importance = ActivityManager.RunningAppProcessInfo.IMPORTANCE_FOREGROUND }
+        shadowOf(application.getSystemService(ActivityManager::class.java)).setProcesses(listOf(processInfo))
+
+        handleMessage(MessagingManager.COMMAND_SCREEN_OFF)
+
+        assertEquals(
+            ScreenOffAdminRequestActivity::class.java.name,
+            shadowOf(application).nextStartedActivity?.component?.className,
+        )
+    }
+}