Skip to content

Commit 1b8ce6d

Browse files
rkoshakConfectrician
authored andcommitted
Added documentation for Member of Rule triggers (openhab#759)
This applies to OH 2.3, not sure how to back port it. While I was here, I also added a warning that if one uses received command, one cannot use ItemName.state and should instead use receivedCommand. Signed off by Richard Koshak <rlkoshak@gmail.com> Addresses openhab#758
1 parent 0a7386d commit 1b8ce6d

File tree

1 file changed

+33
-0
lines changed

1 file changed

+33
-0
lines changed

configuration/rules-dsl.md

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -106,6 +106,7 @@ Before a rule starts working, it has to be triggered.
106106
There are different categories of rule triggers:
107107

108108
- **Item**(-Event)-based triggers: They react on events on the openHAB event bus, i.e. commands and status updates for items
109+
- **Member of**(-Event)-based triggers: They react on events on the openHAB event bus for Items that are a member of the supplied Group
109110
- **Time**-based triggers: They react at special times, e.g. at midnight, every hour, etc.
110111
- **System**-based triggers: They react on certain system statuses.
111112
- **Thing**-based triggers: They react on thing status, i.e. change from ONLINE to OFFLINE.
@@ -127,6 +128,29 @@ Item <item> changed [from <state>] [to <state>]
127128

128129
A simplistic explanation of the differences between `command` and `update` can be found in the article about [openHAB core actions](/docs/configuration/actions.html#event-bus-actions).
129130

131+
An important warning is worth mentioning here.
132+
When using the `received command` trigger, the Rule will trigger **before** the Item's state is updated.
133+
Therefore, if the Rule needs to know what the command was, use the [implicit variable]({{base}}/configuration/rules-dsl.html#implicit-variables-inside-the-execution-block) `receivedCommand` instead of ItemName.state.
134+
135+
{: #member-of-triggers}
136+
### Member of Triggers
137+
138+
As with Item based event-based triggers discussed above, you can listen for commands, status updates, or status changes on the members of a given Group.
139+
You can also decide whether you want to catch only a specific command/status or any.
140+
All of the [implicit variables]({{base}}/configuration/rules-dsl.html#implicit-variables-inside-the-execution-block) get populated using the Item that caused the event.
141+
Of particular note, the implicit variable `triggeringItem` is populated with the Item that caused the Rule to trigger.
142+
143+
```java
144+
Member of <group> received command [<command>]
145+
Member of <group> received update [<state>]
146+
Member of <group> changed [from <state>] [to <state>]
147+
```
148+
149+
The `Member of` trigger only works with Items that are a direct member of the Group.
150+
It does not work with members of nested subgroups.
151+
Also, as with Item event-based triggers, when using `received command`, the Rule will trigger before the Item's state is updated.
152+
So in Rules where the Rule needs to know what the command was, use the `receivedCommand` implicit variable instead of `triggeringItem.state`.
153+
130154
{: #time-based-triggers}
131155
### Time-based Triggers
132156

@@ -806,6 +830,15 @@ when
806830
then
807831
counter = receivedCommand as DecimalType
808832
end
833+
834+
// turns on a light when one of several motion sensors received command ON, turns it off when one of several received command OFF
835+
rule "Motion sensor light"
836+
when
837+
Member of MotionSensors received command
838+
then
839+
if(receivedCommand == ON) Light.sendCommand(ON)
840+
else Light.sendCommand(OFF)
841+
end
809842
```
810843

811844
## Further Examples

0 commit comments

Comments
 (0)