From 18c0c702fe40b6482b7668b971f971567da1acac Mon Sep 17 00:00:00 2001 From: Mark Francis Date: Sat, 11 Jul 2026 10:48:05 -0400 Subject: [PATCH 1/3] Add notification command_screen_off --- docs/notifications/commands.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/docs/notifications/commands.md b/docs/notifications/commands.md index 8d4aa6823b2..02cf6568638 100644 --- a/docs/notifications/commands.md +++ b/docs/notifications/commands.md @@ -44,6 +44,7 @@ The Companion apps offer a lot of different notification options. In place of po | `command_media` | Control media playing on the device, [see below](#media) for how it works and whats required. | | `command_ringer_mode` | Control the ringer mode on the device, [see below](#ringer-mode) for how it works and whats required. | | `command_screen_brightness_level` | Control the screen brightness level on the device. | +| `command_screen_off` | BETA Turn off the device screen while it stays awake and connected, [see below](#screen-off) for how it works and whats required. | | `command_screen_off_timeout` | Control the screen off timeout on the device. | | `command_screen_on` | Turn on the device screen. | | `command_stop_tts`* | Stops Text To Speech if it's currently in use. | @@ -718,6 +719,31 @@ automation: command: 50 ``` +## Screen Off + +![Android](/assets/android.svg) + +BETA On Android you can turn off the display while the device stays awake, unlocked and connected by sending `message: command_screen_off`. This is aimed at wall mounted dashboards where the server decides when the panel should be dark, for example based on presence or a night mode, without putting the device to sleep. The device keeps receiving commands, so `command_screen_on` turns the screen back on at any time. Sending the command again while the screen is already off turns the display off again in case it was woken manually. + +This command requires activating Home Assistant as a device admin, which the app is unable to prompt or auto-accept. The first time you send the command the app will open the system screen to activate it. The device admin holds only the policy needed to turn the screen off. + +If the device has a secure lock screen (PIN, pattern or password) the command is refused and the notification will post as normal, since turning the screen off would lock the device behind credentials. Deactivating the device admin while the screen is off turns it back on so the device is never left unable to sleep. + +:::tip +To keep receiving commands over local push while the screen is off, set the [persistent connection](#persistent) to `always`. +::: + +```yaml +automation: + - alias: Screen off + trigger: + ... + action: + - action: notify.mobile_app_ + data: + message: "command_screen_off" +``` + ## Screen Off Timeout ![Android](/assets/android.svg) From 58150f7626ce9d8342cfe0347ff9fce9219fc306 Mon Sep 17 00:00:00 2001 From: Mark Francis Date: Sun, 19 Jul 2026 17:11:01 -0400 Subject: [PATCH 2/3] Screen off affects only the display; document the two-step activation Co-Authored-By: Claude Opus 4.8 --- docs/notifications/commands.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/notifications/commands.md b/docs/notifications/commands.md index 02cf6568638..a70293796fb 100644 --- a/docs/notifications/commands.md +++ b/docs/notifications/commands.md @@ -44,7 +44,7 @@ The Companion apps offer a lot of different notification options. In place of po | `command_media` | Control media playing on the device, [see below](#media) for how it works and whats required. | | `command_ringer_mode` | Control the ringer mode on the device, [see below](#ringer-mode) for how it works and whats required. | | `command_screen_brightness_level` | Control the screen brightness level on the device. | -| `command_screen_off` | BETA Turn off the device screen while it stays awake and connected, [see below](#screen-off) for how it works and whats required. | +| `command_screen_off` | BETA Turn off the device screen, [see below](#screen-off) for how it works and whats required. | | `command_screen_off_timeout` | Control the screen off timeout on the device. | | `command_screen_on` | Turn on the device screen. | | `command_stop_tts`* | Stops Text To Speech if it's currently in use. | @@ -723,11 +723,11 @@ automation: ![Android](/assets/android.svg) -BETA On Android you can turn off the display while the device stays awake, unlocked and connected by sending `message: command_screen_off`. This is aimed at wall mounted dashboards where the server decides when the panel should be dark, for example based on presence or a night mode, without putting the device to sleep. The device keeps receiving commands, so `command_screen_on` turns the screen back on at any time. Sending the command again while the screen is already off turns the display off again in case it was woken manually. +BETA On Android you can turn off the display by sending `message: command_screen_off`. This is aimed at wall mounted dashboards where the server decides when the panel should be dark, for example based on presence or a night mode. Only the display is affected: whether the device keeps receiving commands while the screen is off depends on your connection settings, and with a [persistent connection](#persistent) `command_screen_on` turns the screen back on at any time. Sending the command again while the screen is already off turns the display off again in case it was woken manually. -This command requires activating Home Assistant as a device admin, which the app is unable to prompt or auto-accept. The first time you send the command the app will open the system screen to activate it. The device admin holds only the policy needed to turn the screen off. +This command requires activating Home Assistant as a device admin, which the app is unable to prompt or auto-accept. When you send the command while the app is open, the app opens the system screen to activate it; when the app is in the background, a missing-permission notification is shown instead. Send the command again after activating. The device admin holds only the policy needed to turn the screen off. -If the device has a secure lock screen (PIN, pattern or password) the command is refused and the notification will post as normal, since turning the screen off would lock the device behind credentials. Deactivating the device admin while the screen is off turns it back on so the device is never left unable to sleep. +If the device has a secure lock screen (PIN, pattern or password) the command is refused and the notification will post as normal, since turning the screen off would lock the device behind credentials. Deactivating the device admin while the screen is off turns it back on. :::tip To keep receiving commands over local push while the screen is off, set the [persistent connection](#persistent) to `always`. From 479b289898338182afa02d1de5199b360ba9e51e Mon Sep 17 00:00:00 2001 From: Mark Francis Date: Sun, 19 Jul 2026 17:38:34 -0400 Subject: [PATCH 3/3] The device admin is never requested behind a secure lock screen Co-Authored-By: Claude Opus 4.8 --- docs/notifications/commands.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/notifications/commands.md b/docs/notifications/commands.md index a70293796fb..ba2c53bc275 100644 --- a/docs/notifications/commands.md +++ b/docs/notifications/commands.md @@ -727,7 +727,7 @@ automation: This command requires activating Home Assistant as a device admin, which the app is unable to prompt or auto-accept. When you send the command while the app is open, the app opens the system screen to activate it; when the app is in the background, a missing-permission notification is shown instead. Send the command again after activating. The device admin holds only the policy needed to turn the screen off. -If the device has a secure lock screen (PIN, pattern or password) the command is refused and the notification will post as normal, since turning the screen off would lock the device behind credentials. Deactivating the device admin while the screen is off turns it back on. +If the device has a secure lock screen (PIN, pattern or password) the command is refused — and the device admin activation is never requested — since turning the screen off would lock the device behind credentials. :::tip To keep receiving commands over local push while the screen is off, set the [persistent connection](#persistent) to `always`.