mirror of https://github.com/nymea/nymea.git
95 lines
4.7 KiB
Plaintext
95 lines
4.7 KiB
Plaintext
/*!
|
|
\page rules.html
|
|
\title Rules
|
|
|
|
\annotatedlist rules
|
|
|
|
\section1 Introduction
|
|
|
|
Rules define all the logic in nymea.
|
|
A rule is composed by a set of \l{Event}{Events}, \l{State}{States} and \l{Action}{Actions}.
|
|
|
|
This diagram shows how rules are composed and interpreted by
|
|
the \l{nymeaserver::RuleEngine}.
|
|
|
|
\image Rules_definition.svg "Rules definition"
|
|
|
|
A basic concept of a \l{nymeaserver::Rule} is the trigger path. This is the path that defines when a \l{nymeaserver::Rule}
|
|
is triggered for evaluation. Each element added on a trigger path (either red or blue) has the possibility to trigger the
|
|
\l{nymeaserver::RuleEngine} to evaluate the complete rule and ultimately execute the defined \l{Action}{Actions} if the
|
|
whole rule evaluates to true. Once the trigger path has been left (i.e. a black arrow is followed),
|
|
subsequent elements will still be evaluated when the rule is triggered, but they won't trigger the
|
|
evaluation themselves.
|
|
|
|
There are two mechanisms that can trigger a rule, described by the two trigger paths in the Rules definition figure.
|
|
\list
|
|
\li State bindings based
|
|
\li Event based
|
|
\endlist
|
|
|
|
\section2 Event based rules
|
|
|
|
Event based rules (trigger path 1) contain either one or more \l{Event}{Events} or are triggered by a \l{State} change (disregarding what
|
|
the changed State's value actually is). Such rules may still evaluate \l{State}{States} for a certain value (leaving
|
|
Trigger path 1 and re-entering Trigger path 2), however, unless
|
|
otherwise explicitly defined, the Rule is not evaluated when such a State change happens (given the Trigger path has been
|
|
left by crossing a black arrow). Those rules are only executed for items on trigger path 1.
|
|
|
|
\section3 Examples
|
|
|
|
\list
|
|
\li This rule will be evaluated and executed whenever Remote_button1 is pressed:
|
|
|
|
\tt {\span {id="color-blue"} {Event<Remote_button1_pressed>}} \tt {\span {id="color-black"} {-> Action<Toggle_Light>}}
|
|
|
|
\li This rule will be evaluated and executed whenever Remote_button1 is pressed or or Motion sensor 1 triggers.
|
|
|
|
\tt {\span {id="color-blue"} {Event<Remote_button1_pressed> | Event<Motion_sensor1_triggered>}} \tt {\span {id="color-black"} {-> Action<Turn_on_Light>}}
|
|
|
|
\li This rule will be evaluated and executed whenever Remote_button1 is pressed or the temperature changes.
|
|
|
|
\tt {\span {id="color-blue"} {Event<Remote_button1_pressed> | State<Temperature_changed>}} \tt {\span {id="color-black"} {-> Action<Turn_on_Light>}}
|
|
\endlist
|
|
|
|
\section2 State bindings based rules
|
|
|
|
State binding rules (Trigger path 2) are rules which only contains \l{State}{States} and \l{Action}{Actions}. Each time
|
|
a \l{State} on that path changes, the rule is evaluated. That means, all the States in the Rule are examined. If all
|
|
evaluations are fulfilled, the Rule's \l{Action}{Actions} are executed. Please note, that such Rules may only check
|
|
if states are equal to, unequal, less than or greater then some value.
|
|
|
|
\section3 Examples
|
|
|
|
\list
|
|
\li This rule will be evaluated whenever the temperature changes and executed when the temperature equals 10.
|
|
|
|
\tt {\span {id="color-red"} {State<Temperature>==10}} \tt {\span {id="color-black"} {-> Action<Toggle_Light>}}
|
|
|
|
\li This rule will be evaluated whenever the temperature changes or the Light sensor changes and executed when the temperature is greater 20 and the light sensor reports values greater 10.
|
|
|
|
\tt {\span {id="color-blue"} {State<Temperature> >20 & State<Light> >10}} \tt {\span {id="color-black"} {-> Action<OpenWindow>}}
|
|
|
|
\li This rule will be evaluated whenever the temperature changes or the Light sensor changes and executed when the temperature is greater 20 or the light sensor reports values greater 10..
|
|
|
|
\tt {\span {id="color-blue"} {State<Temperature> >20 | State<Light> >10}} \tt {\span {id="color-black"} {-> Action<OpenWindow>}}
|
|
\endlist
|
|
|
|
\section2 Mixing rules types
|
|
|
|
Having both types of triggers in a single rule is only possible by leaving the trigger path 1, crossing a black arrow and
|
|
re-entering trigger path 2. This however, converts the rule to an Event based rule which means, only the elements
|
|
on trigger path 1 will be able to trigger the rule evaluation.
|
|
|
|
\section3 Examples
|
|
|
|
\list
|
|
\li This rule will be evaluated whenever the remote button1 is pressed and executed only if the temperature is greater 10.
|
|
|
|
\tt {\span {id="color-blue"} {Event<Button1_pressed>==10}} \tt {\span {id="color-black"} {->}} \tt {\span {id="color-red"} {State<Temperature> >10}} \tt {\span {id="color-black"} {-> Action<Toggle_Light>}}
|
|
|
|
\endlist
|
|
|
|
|
|
*/
|
|
|