github.com/simpleiot/simpleiot@v0.18.3/docs/user/rules.md (about)

     1  # Rules
     2  
     3  **Contents**
     4  
     5  <!-- toc -->
     6  
     7  The Simple IoT application has the ability to run rules -- see the video below
     8  for a demo:
     9  
    10  <iframe width="640" height="360" src="https://www.youtube.com/embed/pb_a6oEdFJI" title="Simple IoT Rules Demo" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
    11  
    12  Rules are composed of one or more conditions and actions. All conditions must be
    13  true for the rule to be active.
    14  
    15  Node point changes cause rules of any parent node in the tree to be run. This
    16  allows general rules to be written higher in the tree that are common for all
    17  device nodes (for instance device offline).
    18  
    19  In the below configuration, a change in the SBC propagates up the node tree,
    20  thus both the `D5 on rule` or the `Device offline rule` are eligible to be run.
    21  
    22  ![rules](images/rules.png)
    23  
    24  ## Node linking
    25  
    26  Both conditions and actions can be linked to a node ID. If you copy a node, its
    27  ID is stored in a virtual clipboard and displayed at the top of the screen. You
    28  can then paste this node ID into the Node ID field in a condition or action.
    29  
    30  ![rule-linking](images/rule-copy-paste-node-id.png)
    31  
    32  ## Conditions
    33  
    34  Each condition may optionally specify a minimum active duration before the
    35  condition is considered met. This allows timing to be encoded in the rules.
    36  
    37  ### Node state
    38  
    39  A point value condition looks at the point value of a node to determine if a
    40  condition is met. Qualifiers that filter points the condition is interested in
    41  may be set including:
    42  
    43  - node ID (if left blank, any node that is a descendent of the rule parent)
    44  - point type ("value" is probably the most common type)
    45  - point Key (used to index into point arrays and objects)
    46  
    47  If the provided qualification is met, then the condition may check the point
    48  value/text fields for a number of conditions including:
    49  
    50  - number: `>`, `<`, `=`, `!=`
    51  - text: `=`, `!=`, `contains`
    52  - boolean: `on`, `off`
    53  
    54  ### Schedule
    55  
    56  Rule conditions can be driven by a schedule that is composed of:
    57  
    58  - start/stop time
    59  - weekdays
    60  - dates
    61  
    62  If no weekdays are selected, then all weekdays are included.
    63  
    64  When the dates are used, then weekdays are disabled.
    65  
    66  Conversely, when a weekday is enabled, dates are disabled.
    67  
    68  As a time range can span two days, the start time is used to qualify weekdays
    69  and dates.
    70  
    71  <img src="./images/rule-schedule.png" alt="image-20230721173842815" style="zoom:67%;" />
    72  
    73  See also a video demo:
    74  
    75  <iframe width="791" height="445" src="https://www.youtube.com/embed/WllM0acCOss" title="Creating an Alarm Clock with Simple IoT schedules" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
    76  
    77  ## Actions
    78  
    79  Every action has an optional repeat interval. This allows rate limiting of
    80  actions like notifications.
    81  
    82  ### Notifications
    83  
    84  Notifications are the simplest rule action and are sent out when:
    85  
    86  - all conditions are met
    87  - time since last notification is greater than the notify action repeat
    88    interval.
    89  
    90  Every time a notification is sent out by a rule, a point is created/updated in
    91  the rule with the following fields:
    92  
    93  - id: node of point that triggered the rule
    94  - type: "lastNotificationSent"
    95  - time: time the notification was sent
    96  
    97  Before sending a notification we scan the points of the rule looking for when
    98  the last notification was sent to decide if its time to send it.
    99  
   100  ### Set node point
   101  
   102  Rules can also set points in other nodes. For simplicity, the node ID must be
   103  currently specified along with point parameters and a number/bool/text value.
   104  
   105  Typically a rule action is only used to set one value. In the case of on/off
   106  actions, one rule is used to turn a value on, and another rule is used to turn
   107  the same value off. This allows for hysteresis and more complex logic than in
   108  one rule handled both the on and off states. This also allows the rules logic to
   109  be stateful. If you don't need hystersis or complex state, the rule "inactive
   110  action" can be used, which allows the rule to take action when it goes both
   111  active and inactive.
   112  
   113  ## Disable Rule/Condition/Action
   114  
   115  ![rule-disable](images/rule-disable.png)
   116  
   117  ### Disable Rule
   118  
   119  A rule can be disabled. If the rule is disabled while active, then the rule
   120  inactive actions are run so that things get cleaned up if necessary and the
   121  actions are not left active.
   122  
   123  ### Disable Condition
   124  
   125  If there are no conditions, or all conditions are disabled, the rule is
   126  inactive. Otherwise, disabled conditions are simply ignored. For example if
   127  there is a disabled condition and an non-disabled active condition, the rule is
   128  active.
   129  
   130  ### Disable Action
   131  
   132  A disabled action is not run.