Wake a screen or put it to sleep from Home Assistant (0.2.53)

Every screen gets two template buttons, Wake and Sleep, for automations
(button.press on button.<screen>_wake / _sleep). Wake does what a tap does:
a dimmed screen runs wake_display, a screen that is on only restarts the
standby count. Sleep dims right away through dim_display, also with Auto
standby off, and closes an alert that is up (reported as remote); it is
ignored during a touch calibration.

A new non-restored flag, sleep_requested, keeps that standby in place:
dim_display dims with standby off, and apply_screen_settings, which runs
every minute, no longer wakes such a screen. wake_display clears it (a tap,
Wake, an alert), and so does the Auto standby switch when it really turns
standby off. Nothing is saved, so the buttons cost no flash writes and may
run on every motion.

The Claude skill, README, add-on docs and RELEASING describe both buttons.
Checked on host builds of both boards over the native API, 24 checks each
(timer, Sleep with Auto standby off across a minute tick, alert,
calibration), and with ESP32 builds of both Easy profiles (+336 B RAM).
Firmware 0.2.45.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

tests/test_claude_skill.py

@@ -12,7 +12,8 @@ sys.path.insert(0, str(ROOT / 'screen_manager/app'))
 import claude_skill  # noqa: E402
 import tile_icons  # noqa: E402
 from core import (ALERT_EVENT, ALERT_FIELDS, ALERT_LIMITS, ALERT_MIN_FIRMWARE, AUTO_STANDBY_MIN_FIRMWARE, BROADCAST_DISMISS,  # noqa: E402
-                  BROADCAST_SHOW, CONTROLS, DISPLAYS, TILE_BACKGROUNDS, TILE_EVENTS, TILE_RESULT_EVENT)
+                  BROADCAST_SHOW, CONTROLS, DISPLAYS, TILE_BACKGROUNDS, TILE_EVENTS, TILE_RESULT_EVENT,
+                  WAKE_SLEEP_MIN_FIRMWARE)
 
 HAS_YAML = importlib.util.find_spec('yaml') is not None
 HAS_AIOHTTP = importlib.util.find_spec('aiohttp') is not None
@@ -51,6 +52,11 @@ class SkillText(unittest.TestCase):
                        'number.<screen>_standby_brightness', 'number.<screen>_night_brightness'):
             self.assertIn(f'`{entity}`', standby)
         self.assertIn(AUTO_STANDBY_MIN_FIRMWARE, standby)
+        # Wake and Sleep (0.2.53): the buttons, when they arrived, and how to press several at once.
+        for entity in ('button.<screen>_wake', 'button.<screen>_sleep'):
+            self.assertIn(f'`{entity}`', standby)
+        self.assertIn(f'Firmware {WAKE_SLEEP_MIN_FIRMWARE} or newer', standby)
+        self.assertIn('`button.press`', standby)
         self.assertIn('(#standby-and-brightness)', text, 'the intro links to the section')
         # Tiles (0.2.51): the events, what a tile can do per domain, how to read a screen and the rule to ask first.
         tiles = text.split('## Tiles on a screen', 1)[1].split('## All screens', 1)[0]
@@ -72,7 +78,7 @@ class SkillText(unittest.TestCase):
     def test_every_yaml_example_parses(self):
         import yaml
         blocks = re.findall(r'```yaml\n(.*?)```', claude_skill.text(), re.S)
-        self.assertEqual(len(blocks), 8)
+        self.assertEqual(len(blocks), 9)
         parsed = [yaml.safe_load(block) for block in blocks]
         # Tiles first (0.2.51): putting one on a screen, and ordering a page.
         self.assertEqual(parsed[0]['actions'][0]['event'], 'esp_screens_add_tile')
@@ -85,7 +91,20 @@ class SkillText(unittest.TestCase):
         self.assertEqual(parsed[4][0]['wait_for_trigger'][0]['event_type'], ALERT_EVENT)
         choose = parsed[5]['actions'][0]['choose']
         self.assertEqual([option['sequence'][0]['event'] for option in choose], [BROADCAST_SHOW, BROADCAST_DISMISS])
-        awake = parsed[6]
+        # Wake on motion for one screen, Sleep for two, each branch on its own trigger.
+        buttons = parsed[6]
+        options = buttons['actions'][0]['choose']
+        self.assertEqual({trigger['id'] for trigger in buttons['triggers']}, {option['conditions'][0]['id'] for option in options})
+        pressed = []
+        for option in options:
+            step = option['sequence'][0]
+            self.assertEqual(step['action'], 'button.press')
+            targets = step['target']['entity_id']
+            pressed.append([targets] if isinstance(targets, str) else targets)
+        self.assertTrue(all(entity.startswith('button.') and entity.endswith('_wake') for entity in pressed[0]))
+        self.assertTrue(all(entity.startswith('button.') and entity.endswith('_sleep') for entity in pressed[1]))
+        self.assertGreater(len(pressed[1]), 1, 'shows how to reach several screens at once')
+        awake = parsed[7]
         self.assertEqual(awake['mode'], 'restart')
         branch = awake['actions'][0]
         self.assertEqual((branch['then'][0]['action'], branch['else'][0]['action']), ('switch.turn_off', 'switch.turn_on'))

tests/test_settings_page.py

@@ -91,7 +91,8 @@ class Firmware(unittest.TestCase):
             self.assertIn('- action: open_settings', text, name)
             self.assertIn('- id: go_home', text, name)
             self.assertIn('runtime_tiles::auto_home', text, name)
-            self.assertIn('SCREEN_FIRMWARE_VERSION: "0.2.44"', text, name)
+            version = re.search(r'SCREEN_FIRMWARE_VERSION: "([0-9.]+)"', text)[1]
+            self.assertGreaterEqual(tuple(map(int, version.split('.'))), (0, 2, 44), name)
 
     def test_the_hold_strip_covers_the_top_bar_and_no_more(self):
         for name, text in self.profiles.items():

tests/test_wake_sleep.py

@@ -0,0 +1,96 @@
+"""Wake and Sleep buttons for Home Assistant automations (app 0.2.53, firmware 0.2.45).
+
+Both board profiles have to wire them the same way: Wake is a tap, Sleep is the standby time running out
+right away, and a Sleep holds with Auto standby off until a tap, Wake or an alert ends it.
+"""
+import re
+import sys
+import unittest
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / 'screen_manager/app'))
+from core import FIRMWARE_VERSION, WAKE_SLEEP_MIN_FIRMWARE  # noqa: E402
+
+PROFILES = ('home-like-2432s028.yaml', 'guition-4848s040.yaml', 'packages/cyd.yaml', 'packages/guition.yaml')
+
+
+def section(text, top):
+    """One top-level YAML section of a profile, up to the next one."""
+    match = re.search(rf'^{top}:\n(.*?)(?=^[a-z_]+:|\Z)', text, re.M | re.S)
+    return match[1] if match else ''
+
+
+def item(text, key, value):
+    """The list item in a section that carries `key: value`, up to the next item at the same depth."""
+    for chunk in re.split(r'^  - ', text, flags=re.M)[1:]:
+        if re.search(rf'^\s*{key}: "?{re.escape(value)}"?$', chunk, re.M):
+            return chunk
+    return ''
+
+
+def script(text, name):
+    return item(section(text, 'script'), 'id', name)
+
+
+class Profiles(unittest.TestCase):
+    def setUp(self):
+        self.profiles = {name: (ROOT / name).read_text() for name in PROFILES}
+
+    def test_the_firmware_that_carries_the_buttons_is_this_release_or_older(self):
+        version = lambda text: tuple(int(part) for part in text.split('.'))
+        self.assertLessEqual(version(WAKE_SLEEP_MIN_FIRMWARE), version(FIRMWARE_VERSION))
+
+    def test_both_buttons_are_plain_controls_home_assistant_sees(self):
+        for name, text in self.profiles.items():
+            buttons = section(text, 'button')
+            for label in ('Wake', 'Sleep'):
+                button = item(buttons, 'name', label)
+                self.assertTrue(button, f'{name}: no {label} button')
+                self.assertIn('platform: template', button, name)
+                self.assertNotIn('entity_category', button, f'{name}: {label} is a control, not a setting')
+                self.assertNotIn('internal', button, f'{name}: {label} must reach Home Assistant')
+
+    def test_wake_is_a_tap(self):
+        for name, text in self.profiles.items():
+            wake = item(section(text, 'button'), 'name', 'Wake')
+            # A dimmed screen wakes the way the tap on its wake overlay does; one that is on only counts again.
+            self.assertRegex(wake, r"return id\(display_dimmed\);'\s+then:\s+- script\.execute: wake_display\s+else:\s+"
+                                   r"- lambda: 'id\(last_touch_ms\) = millis\(\);'", name)
+            self.assertIn('id(sleep_requested) = false;', script(text, 'wake_display'), f'{name}: waking ends a Sleep')
+            overlay = re.search(r'id: dim_wake_overlay\n.*?on_click:\s+- script\.execute: (\w+)', text, re.S)
+            self.assertEqual(overlay[1], 'wake_display', f'{name}: a tap and Wake share one path')
+
+    def test_sleep_dims_now_and_holds_with_auto_standby_off(self):
+        for name, text in self.profiles.items():
+            sleep = item(section(text, 'button'), 'name', 'Sleep')
+            # Not during a touch calibration (said in the log); otherwise the flag, a closed alert, then the dim.
+            self.assertRegex(sleep, r"return id\(calibration_active\);'\s+then:\s+- lambda: 'ESP_LOGI\(\"standby\", \"Sleep from Home Assistant ignored", name)
+            steps = re.findall(r'script\.execute:(?:\s+id:)?\s+(\w+)|(id\(sleep_requested\) = true;)', sleep.split('else:', 1)[1])
+            self.assertEqual([step[0] or 'flag' for step in steps], ['flag', 'alert_dismiss', 'dim_display'], name)
+            self.assertIn('reason: "remote"', sleep, f'{name}: HA hears the alert was closed from Home Assistant')
+            dim = script(text, 'dim_display')
+            self.assertIn("lambda: 'return screen_settings::current.standby_enabled || id(sleep_requested);'", dim, name)
+            apply = script(text, 'apply_screen_settings')
+            self.assertIn('if (id(display_dimmed) && !settings.standby_enabled && !id(sleep_requested)) {', apply,
+                          f'{name}: the minute tick must not undo a Sleep')
+            self.assertEqual(len(re.findall(r'id\(sleep_requested\) = true;', text)), 1, f'{name}: only the button starts a Sleep')
+
+    def test_the_flag_starts_false_and_is_never_saved(self):
+        for name, text in self.profiles.items():
+            flag = item(section(text, 'globals'), 'id', 'sleep_requested')
+            self.assertIn('type: bool', flag, name)
+            self.assertIn('restore_value: no', flag, name)
+            self.assertIn("initial_value: 'false'", flag, name)
+
+    def test_switching_auto_standby_off_still_wakes_the_screen(self):
+        for name, text in self.profiles.items():
+            switch = item(section(text, 'switch'), 'name', 'Auto standby')
+            off = switch.split('turn_off_action:', 1)[1]
+            # Only a real change wakes: a switch that was already off returns before the flag is touched.
+            self.assertRegex(off, r'if \(!s\.standby_enabled\) return;\s+s\.standby_enabled = false;\s+(//[^\n]*\n\s+)?'
+                                  r'id\(sleep_requested\) = false;', name)
+
+
+if __name__ == '__main__':
+    unittest.main()