github.com/e154/smart-home@v0.17.2-0.20240311175135-e530a6e5cd45/doc/content/en/docs/dashboard/automation/triggers.md (about)

     1  
     2  ---
     3  title: "Triggers"
     4  linkTitle: "Triggers"
     5  date: 2021-10-20
     6  description: >
     7    
     8  ---
     9  
    10  {{< figure src="/smart-home/triggers_window1.png" >}}
    11  
    12  Triggers in the Smart Home system are key elements that initiate the execution of tasks in response to specific events or conditions. Currently, the system supports three main types of triggers, each with its advantages, providing flexibility in automation configuration.
    13  
    14  #### 1. **Trigger "State Change":**
    15  
    16  - **Description:**
    17      - Activates upon the change of the state of a specific device or group of devices in the Smart Home system.
    18  
    19  - **Advantages:**
    20      - **Reacting to Changes:** Ideal for scenarios where specific reactions are needed, such as turning lights on/off, opening doors, etc.
    21      - **Customization Flexibility:** Allows selecting specific devices and state parameters for triggering.
    22  
    23  #### 2. **Trigger "System":**
    24  
    25  - **Description:**
    26      - Activates upon the occurrence of system events, such as system start/stop, device connection/disconnection, and other events on the system bus.
    27  
    28  - **Advantages:**
    29      - **System Monitoring:** Used for monitoring the overall system state and detecting events related to the functioning of the smart home.
    30      - **Integration with External Systems:** Enables interaction with systems operating within the system bus.
    31  
    32  #### 3. **Trigger "Time (Cron)":**
    33  
    34  - **Description:**
    35      - Activates at specified time intervals according to a schedule defined in cron format.
    36  
    37  - **Advantages:**
    38      - **Regular Execution:** Ideal for tasks that need to be executed regularly on a schedule.
    39      - **Energy Savings:** Can be used to optimize energy consumption, such as turning off lights or heating during nighttime.
    40  
    41  #### Examples of Trigger Usage
    42  
    43  1. **Trigger "State Change":**
    44      - **Scenario:**
    45          - Turn on the air conditioner when the window in the bedroom is opened.
    46      - **Trigger Configuration:**
    47          - Device: Window in the bedroom.
    48          - State: Open.
    49  
    50  2. **Trigger "System":**
    51      - **Scenario:**
    52          - Send a notification upon connecting a new device to the system.
    53      - **Trigger Configuration:**
    54          - System Event: Connection of a new device.
    55  
    56  3. **Trigger "Time (Cron)":**
    57      - **Scenario:**
    58          - Turn off the lights in all rooms after midnight.
    59      - **Trigger Configuration:**
    60          - Time Interval: "0 0 * * *" corresponding to every midnight.
    61  
    62  #### Examples in Coffeescript
    63  
    64  1. `TriggerAlexa`:
    65  ```coffeescript
    66  automationTriggerAlexa = (msg) ->
    67    p = msg.payload
    68    Done p
    69    return false
    70  ```
    71  The `automationTriggerAlexa` handler is called in response to a trigger from Amazon Alexa. It takes the message object `msg` and can perform specific actions related to this trigger.
    72  
    73  2. `TriggerStateChanged`:
    74  ```coffeescript
    75  automationTriggerStateChanged = (msg) ->
    76    p = msg.payload
    77    Done p.new_state.state.name
    78    return false
    79  ```
    80  The `automationTriggerStateChanged` handler is called when the state of a device changes. It takes the message object
    81  `msg` and can perform specific actions based on the new state of the device.
    82  
    83  3. `TriggerSystem`:
    84  ```coffeescript
    85  automationTriggerSystem = (msg) ->
    86    p = msg.payload
    87    Done p.event
    88    return false
    89  ```
    90  The `automationTriggerSystem` handler is called in response to system events. It takes the message object `msg` and can perform specific actions related to this event.
    91  
    92  4. `TriggerTime`:
    93  ```coffeescript
    94  automationTriggerTime = (msg) ->
    95    p = msg.payload
    96    Done p
    97    return false
    98  ```
    99  The `automationTriggerTime` handler is called after a specified period of time has elapsed. It takes the message object `msg` and can perform specific actions related to this time.
   100  
   101  Each trigger handler can execute the necessary logic in response to the corresponding trigger and then return the value `false` to indicate that further processing is not required.
   102  
   103  Example implementation:
   104  
   105  ```coffeescript
   106  automationTriggerStateChanged = (msg)->
   107      p = msg.payload
   108      if !p.new_state || !p.new_state.state
   109          return false
   110      return msg.new_state.state.name == 'DOUBLE_CLICK'
   111  ```
   112  
   113  #### Conclusion
   114  
   115  The use of different types of triggers in the Smart Home system allows users to create complex and intelligent automation scenarios that seamlessly respond to changes in the system and external events. This provides users with a personalized and efficient smart home experience.