various tidyups

packages/simulation_lights.yaml

@@ -1,8 +1,39 @@
+#:########################################################################################:#
+# Package: Away-Light Security Simulation
+# File:    simulation_lights.yaml
+# Version: v1.0.0
+# Date:    2026-07-24
+#
+# Purpose:
+#   Simulates household activity while the away routine is active and all
+#   configured family members are away. Every five minutes after sunset, the
+#   automation selects a configured entity and operates it for a random period.
+#
+# Version History:
+#   - v1.0.0 (2026-07-24): Consolidated the simulation groups, away automation, and timed helper
+#     script into one feature package.
+#     - Preserved the existing automation ID, group keys, and script key.
+#     - Aligned the automation with the existing simulation_lights_all group.
+#:########################################################################################:#
+
 group:
-  simulation_lights_all:
-    name: Simulation Lights (All)
+  #:######################################################################################:#
+  # FAMILY PRESENCE
+  #:######################################################################################:#
+  family_away:
+    name: "All Family Members Away"
     entities:
-      - group.downstairs_flat_lights # ← now valid here
+      - !secret person_1
+      - !secret person_2
+      - !secret person_3
+
+  #:######################################################################################:#
+  # SIMULATION ENTITIES
+  #:######################################################################################:#
+  simulation_lights_all:
+    name: "Simulation Lights (All)"
+    entities:
+      - group.downstairs_flat_lights
       - switch.esp_centralstairs_top_relay_2_stair_footer_lights
       - switch.esp_centralstairs_bottom_relay_1_main_stair_lights_lower
       - switch.esp_entrancebathrmlights_relay_1_main_lights
@@ -16,3 +47,62 @@ group:
       - light.esp_loungepelmetleds2_lounge_pelmet_leds_a
       - light.esp_lounge6chdimmer_couch_spots_left
       - light.esp_lounge6chdimmer_couch_spots_right
+
+script:
+  #:######################################################################################:#
+  # RANDOM-DURATION ENTITY CONTROL
+  #:######################################################################################:#
+  light_duration:
+    description: "Turns an entity on for a supplied duration and then turns it off."
+    mode: parallel
+    fields:
+      light:
+        description: "Entity to operate."
+        example: light.bedroom
+      duration:
+        description: "How long the entity should remain on."
+        example: "00:25:00"
+    sequence:
+      - action: logbook.log
+        data:
+          name: "Script Notice"
+          message: "Light {{ light }} will be turned on for {{ duration }}"
+
+      - action: homeassistant.turn_on
+        target:
+          entity_id: "{{ light }}"
+
+      - delay: "{{ duration }}"
+
+      - action: homeassistant.turn_off
+        target:
+          entity_id: "{{ light }}"
+
+automation:
+  #:######################################################################################:#
+  # AWAY-LIGHT SIMULATION
+  #:######################################################################################:#
+  - id: do_random_actions_when_away
+    alias: "Activate Random Actions for Security"
+    description: >
+      Periodically runs the timed simulation script after sunset when the away
+      routine is active and all configured family members are away.
+    mode: parallel
+    triggers:
+      - trigger: time_pattern
+        minutes: "/5"
+    conditions:
+      - condition: sun
+        after: sunset
+        after_offset: "-00:30:00"
+      - condition: state
+        entity_id: input_boolean.away_occupied_routine
+        state: "on"
+      - condition: state
+        entity_id: group.family_away
+        state: "not_home"
+    actions:
+      - action: script.light_duration
+        data:
+          light: "{{ state_attr('group.simulation_lights_all', 'entity_id') | random }}"
+          duration: "00:{{ '{:02}'.format(range(5, 29) | random | int) }}:00"