Rules

Contents

The Simple IoT application has the ability to run rules - see the video below for a demo:

Rules are composed of one or more conditions and actions. All conditions must be true for the rule to be active.

Node point changes cause rules of any parent node in the tree to be run. This allows general rules to be written higher in the tree that are common for all device nodes (for instance device offline).

In the below configuration, a change in the SBC propagates up the node tree, thus both the D5 on rule or the Device offline rule are eligible to be run.

Node linking

Both conditions and actions can be linked to a node ID. If you copy a node, its ID is stored in a virtual clipboard and displayed at the top of the screen. You can then paste this node ID into the Node ID field in a condition or action.

Conditions

Each condition may optionally specify a minimum active duration (minActive), in minutes, that it has to hold continuously before it is considered met. This is a pending period, and it keeps a brief spike — a level that grazes a threshold, a device that drops offline for a few seconds — from activating the rule at all. An input that crosses the threshold and returns before the period expires never activates the condition, and the wait starts over the next time it crosses.

A condition may also specify a minimum inactive duration (minInactive), the mirror image of minActive: once the condition is met, it stays met until its input has been clear for that many minutes. An input that returns before the duration expires cancels the wait and the condition never goes inactive, so a value oscillating around a threshold is one incident and one notification rather than one per cycle.

Both durations are in-process state, so they restart if the instance restarts or the rule is edited. Disabling a rule clears them as well.

Together with the repeat interval on a notify action, these durations follow the model Grafana alerting and Prometheus Alertmanager have converged on, because they address the same problems: noisy conditions, flapping, and notification fatigue. Two of Grafana’s defenses are handled elsewhere in Simple IoT rather than in the rule. Evaluating over an aggregation window instead of raw samples belongs in the client producing the point, and a recovery threshold separate from the firing threshold is done with two rules or an inactive action as described in Set node point.

Node state

A point value condition looks at the point value of a node to determine if a condition is met. Qualifiers that filter points the condition is interested in can set including:

• Node ID (if left blank, any node that is a descendant of the rule parent)
• Point type (“value” is probably the most common type)
• Point Key (used to index into point arrays and objects)

If the provided qualification is met, then the condition may check the point value/text fields for a number of conditions including:

• number: >, <, =, !=
• text: =, !=, contains
• boolean: on, off

Schedule

Rule conditions can be driven by a schedule that is composed of:

• start/stop time
• weekdays
• dates

If no weekdays are selected, then all weekdays are included.

When the dates are used, then weekdays are disabled.

Conversely, when a weekday is enabled, dates are disabled.

As a time range can span two days, the start time is used to qualify weekdays and dates.

See also a video demo:

Actions

Actions run when the rule changes state. Actions of type action run on the inactive to active transition, and actions of type actionInactive run on the active to inactive transition. Editing a rule, a condition, or an action while the rule is active does not re-run the actions — only a change of state does.

Disabling a rule makes it inactive, which is a transition like any other, so disabling an active rule runs its inactive actions once and further edits while it stays disabled run nothing.

Rule state is persisted, so a restart resumes in the state the rule was in and does not re-run the actions or re-send the notification for a state that has not changed.

Notifications

A notify action publishes a notification point on the rule node each time the rule goes active (or inactive, for an inactive action). The notification carries the rule description as the subject and names the node that triggered the rule in the message. From there it is delivered to users and messaging services in scope as described in the notifications documentation.

Each state transition sends one notification. A notify action may also set a repeat interval, in minutes, which turns on two behaviors at once:

• A reminder. While the rule stays active, an action of type action re-sends its notification every interval, so a long running condition is not a single message that scrolled away hours ago. An inactive action does not repeat — a resolved rule is the normal state, so a reminder about it would never stop.
• A rate limit. An action does not notify more often than its repeat interval no matter how often the rule transitions. The transition still happens and the rule state is still correct; only the notification is dropped. This bounds the damage from a condition that flaps faster than its minActive and minInactive durations guard against.

With no repeat interval set, an action sends one notification per transition and is not rate limited. Send times are in-process state, so they reset if the instance restarts.

Set node point

Rules can also set points in other nodes. For simplicity, the node ID must be currently specified along with point parameters and a number/bool/text value.

Typically a rule action is only used to set one value. In the case of on/off actions, one rule is used to turn a value on, and another rule is used to turn the same value off. This allows for hysteresis and more complex logic than in one rule handled both the on and off states. This also allows the rules logic to be stateful. If you don’t need hysteresis or complex state, the rule “inactive action” can be used, which allows the rule to take action when it goes both active and inactive.

Disable Rule/Condition/Action

Disable Rule

A rule can be disabled. If the rule is disabled while active, then the rule inactive actions are run so that things get cleaned up if necessary and the actions are not left active.

Disable Condition

If there are no conditions, or all conditions are disabled, the rule is inactive. Otherwise, disabled conditions are simply ignored. For example, if there is a disabled condition and a non-disabled active condition, the rule is active.

Disable Action

A disabled action is not run.

Schema

The configuration of a rule with a point value condition, a schedule condition, and an action for each direction:

nodes:
  - rule:
      description: Tank low
      disabled: 0
      children:
        - condition:
            conditionType: pointValue
            description: Level below 10
            disabled: 0
            minActive: 5
            minInactive: 10
            nodeID: Tank level
            operator: <
            pointKey: ""
            pointType: value
            value: 10
            valueType: number
        - condition:
            conditionType: schedule
            description: Working hours
            end: "17:00"
            start: "08:00"
            weekday:
              - 0
              - 1
              - 1
              - 1
              - 1
              - 1
              - 0
        - action:
            action: notify
            description: Tell the operators
            repeatInterval: 240
        - actionInactive:
            action: setValue
            description: Clear the alarm
            nodeID: Alarm relay
            pointType: switchSet
            value: 0
            valueType: onOff

Conditions and actions are children of the rule, and an inactive action is a child of type actionInactive, which is what lets one rule act in both directions.

nodeID names the node a condition watches or an action writes to, and it is written as that node’s description rather than as an ID, so a rule can be moved between instances. Leaving it out of a condition watches every node below the rule’s parent. See referring to another node for how the name is resolved.

conditionType is pointValue or schedule. A point value condition qualifies the points it is interested in with pointType and pointKey, and valueType decides how it compares them: a number condition compares value using operator, one of >, <, =, or !=; a text condition compares valueText using =, !=, or contains; and an onOff condition matches a value of 1 or 0 and needs no operator. minActive is how many minutes the condition has to hold before it is considered met, and minInactive is how many minutes its input has to be clear before it stops being met.

A schedule condition uses start and end, written as text so 08:00 keeps its leading zero, along with weekday and date. weekday is seven points, Sunday first, each 1 or 0. date is a list of dates, and a schedule carries dates or weekdays rather than both.

action is notify, setValue, or playAudio. A notify action takes an optional repeatInterval, in minutes, which reminds while the rule stays active and rate limits the action in both directions. A setValue action names what to write with nodeID, pointType, and pointKey, and what to write with valueType and value or valueText. A playAudio action names the WAV file to play with filePath, the ALSA device to play it on with device, and the channel with channel.

The rule’s active state, its most recent notification, and any error are points the client maintains, so an export of a running rule carries them as well.