"Rules" are used for automating processes: Each rule can be triggered, which invokes a script that performs any kinds of tasks, e.g. turn on lights by modifying your items, do mathematical calculations, start timers etcetera.
openHAB has a highly integrated, lightweight but yet powerful rule engine included.
On this page you will learn how to leverage its functionality to do *real* home automation.
The [demo setup]({{base}}/tutorials/demo.html) already comes with a demo file called `demo.rules`, which has a couple of examples that can be a good starting point.
Note: The rule syntax is based on [Xbase](http://www.eclipse.org/Xtext/#xbase) and as a result it is sharing many details with [Xtend](http://www.eclipse.org/xtend/), which is built on top of Xbase as well.
As a result, we will often point to the Xtend documentation for details.
The **Imports** section contains import statement just like in Java.
As in Java, they make the imported types available without having to use the fully qualified name for them.
For further details, please see the [Xtend documentation for imports](http://www.eclipse.org/xtend/documentation/202_xtend_classes_members.html#imports).
The **Variable Declarations** section can be used to declare variables that should be accessible to all rules in this file.
You can declare variables with or without initial values and modifiable or read-only.
For further details, please see the [Xtend documentation for variable declarations](http://www.eclipse.org/xtend/documentation/203_xtend_expressions.html#variable-declaration).
-`<RULE_NAME>` - Each rule must have a unique name (given within quotes). It is recommended that you choose a name that has meaning when spoken.
-`<TRIGGER_CONDITION>` - The triggering event upon which the rule logic is executed. A rule is executed in reaction to one or more trigger conditions. Multiple conditions are separated by the keyword `or`. Please see below for different possible triggers.
-`<SCRIPT_BLOCK>` - Contains the logic that should be executed when a trigger condition is met, see the [script](#scripts) section for details on its syntax.
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).
When using the `received command` trigger, the Rule will trigger **before** the Item's state is updated.
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.
{: #member-of-triggers}
### Member of Triggers
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.
You can also decide whether you want to catch only a specific command/status or any.
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.
Of particular note, the implicit variable `triggeringItem` is populated with the Item that caused the Rule to trigger.
```java
Member of <group> received command [<command>]
Member of <group> received update [<state>]
Member of <group> changed [from <state>] [to <state>]
```
The `Member of` trigger only works with Items that are a direct member of the Group.
It does not work with members of nested subgroups.
Also, as with Item event-based triggers, when using `received command`, the Rule will trigger before the Item's state is updated.
So in Rules where the Rule needs to know what the command was, use the `receivedCommand` implicit variable instead of `triggeringItem.state`.
You can either use some pre-defined expressions for timers or use a [cron expression](http://www.quartz-scheduler.org/documentation/quartz-2.1.x/tutorials/tutorial-lesson-06) instead:
```java
Time is midnight
Time is noon
Time cron "<cronexpression>"
```
A cron expression takes the form of six or optionally seven fields:
You may also use [CronMaker](http://www.cronmaker.com/) or the generator at [FreeFormatter.com](http://www.freeformatter.com/cron-expression-generator-quartz.html) to generate cron expressions.
| System started | System started is triggered upon openHAB startup, after the rule file containing the System started trigger is modified, or after item(s) related to that rule file are modified in a .items file. |
| System shuts down | Rules using the 'System shuts down' trigger execute when openHAB shuts down. |
Compared with other types of channels, a trigger channel provides information about discrete events, but does not provide continuous state information.
Your rules can take actions based upon trigger events generated by these trigger channels.
You can decide whether you want to catch only a specific or any trigger the channel provides.
Here is the syntax for these cases (parts in square brackets are optional):
> Note: You need to use quotes around `triggerChannel` if it contains special characters such as `:`.
The expression language used within scripts is the same that is used in the Xtend language - see the [documentation of expressions](http://www.eclipse.org/xtend/documentation/203_xtend_expressions.html) on the Xtend homepage.
The syntax is very similar to Java, but has many nice features that allows writing concise code.
It is especially powerful in handling collections.
What makes it a good match for openHAB from a technical perspective is the fact that there is no need to compile the scripts as they can be interpreted at runtime.
Rules are often used to manipulate the state of an Item, for example switching lights on and off under certain conditions.
Two commands can change the value or state of an Item within rules:
-`MyItem.postUpdate(<new_state>)` - Change the status of an Item without causing any implicit actions. Can be used to reflect changes that may be caused by other means.
-`MyItem.sendCommand(<new_state>)` - Change the status of an Item and trigger potential further actions, e.g. send a command to the linked device/binding.
In relation to [event-based rule triggers]({{base}}/configuration/rules-dsl.html#event-based-triggers) the manipulator commands `sendCommand` and `postUpdate` act differently.
The following table summarizes the impact of the two manipulator commands on the rule execution due to the used trigger:
Besides the specific manipulator command methods `MyItem.sendCommand(<new_state>)` and `MyItem.postUpdate(<new_state>)`, generic manipulators in the form of `sendCommand(MyItem, <new_state>)` and `postUpdate(MyItem, <new_state>)` are available. The specific versions is normally recommended.
{: #sendcommand-method-vs-action}
#### MyItem.sendCommand("new state") versus sendCommand(MyItem, "new state")
Using the methods `MyItem.sendCommand(<new_state>)` and `MyItem.postUpdate(<new_state>)` is often preferable.
These are methods of Objects that can accept a variety of types.
Contrary, the Actions `sendCommand(MyItem, "<new_state>")` and `postUpdate(MyItem, "<new_state>")` can only accept strings as arguments.
The reasons lie within Java, the object-oriented programming language on which openHAB is built.
Java and the Rules DSL have two basic types, primitives and Objects.
Objects have special methods that can perform many necessary type conversions automatically.
Using `Myitem.sendCommand(new_state)` or `Myitem.postUpdate(new_state)` will, in most cases, convert `new_state` into a type that Object `myItem` can apply.
Often it is desired to calculate other values from Item states or to compare Item states against other values
In openHAB, every item carries a state.
The state of an Item is an Object itself and can be accessed with `MyItem.state`.
A complete and up-to-date list of item types are currently allowed in OpenHAB and the command types each item can accept is given in the [openHab documentation for items]({{base}}/concepts/items.html).
To use the state of an Item in rules it is often necessary to know what type of state the Item is carrying and how to convert it into types that can be used in such operations.
Conversely, to use the result of a calculation to modify the state of an item may require its transformation into a suitable type.
This section differentiates between command type and state type.
For ease of reading, it is possible to simply add “type” to the end of a command type thereby obtaining the state type.
For example, a Color Item can receive an OnOffType, IncreaseDecreaseType, PercentType, or HSBType.
Therefore the following are all valid commands one can send to a Color Item:
-`MyColorItem.sendCommand(ON)`
-`MyColorItem.sendCommand(INCREASE)`
-`MyColorItem.sendCommand(new PercentType(50))`
-`MyColorItem.sendCommand(new HSBType(new DecimalType(123), new PercentType(45), new PercentType(67)))`
An alternative way to command or update the state of an item is through the use of specially formatted strings.
The section in the [item documentation on formatting]({{base}}/concepts/items.html#state-and-command-type-formatting) details the requirements for the formatting.
Even though many Items accept commands and updates of various different types, each stores its state internally using only one type.
The Color Item from the example above will accept various command types, but will only return an HSBType.
Groups can be declared with any Item type and the internal state of the Group will match that type.
For example, `Group:Switch` will return an OnOffType for its state.
Each State Type provides a number of convenience methods that will greatly aid in conversion and calculations.
- Use the [openHAB VS Code Extension](/docs/configuration/editors.html#editors.html#openhab-vs-code-extension) and the `<ctrl><space>` key combo to list all the available methods
For example, the [JavaDoc for HSBType](http://www.eclipse.org/smarthome/documentation/javadoc/index.html?org/eclipse/smarthome/core/library/types/HSBType.html) shows getRed, getBlue, and getGreen methods.
Thse methods can be called in Rules-DSL without the "get" part in name as in `(MyColorItem.state as HSBType).red)`.
They retrieve the state of MyColorItem and then casts it as HSBType to be able to use the methods associated with the HSBType.
{: #conversions}
#### Working with Item States: Conversions
*Reminder: For a complete and up-to-date list of what item types are currently allowed in openHAB and the command types each item can accept refer to the section on [items in the openHAB documentation]({{base}}/concepts/items.html).*
Below a **non-exhaustive** list of some more common conversions.
The interested reader is encouraged to also visit the [forum](https://community.openhab.org) where many more examples can be found.
##### Conversion of Item.state to String
All Item states can be converted into a string by invoking `MyItem.state.toString`.
##### Color Item
A Color Item stores an **HSBType**.
The HSB stands for Hue, Saturation, and Brightness.
Often one has the desired color as an RGB values (Red, Green, Blue).
The following code can be used to send an RGB value to a Color Item.
```java
import java.awt.Color
// Create item
val newColor = new Color(red, blue, green) // where red, blue, and green are ints between 0 and 255
//Saving to an Item
MyColorItem.sendCommand(new HSBType(newColor))
```
When individual color values from a HSBType as a PercentType are retrieved, it will be necessary to multiply that PercentType by 255 to obtain a standard 8-bit per color channel RGB.
Correspondingly, the for 16 or 32 bit representation, the percent type needs to be multiplied the percent type by 16^2 or 32^2, respectively.
```java
//Example for conversion to 8-bit representation
// In rule body
val red = (MyColorItem.state as HSBType).red * 255
val green = (MyColorItem.state as HSBType).green * 255
val blue = (MyColorItem.state as HSBType).blue * 255
```
##### Contact Item
A Contact Item carries a OpenClosedType.
OpenClosedType is an Enumeration.
One can convert from Open and Closed to 1 and 0 with code similar to:
```java
val contactNum = if (MyContactItem.state == OPEN) 1 else 0
```
##### DateTime Item
A DateTime Item carries a **DateTimeType**.
DateTimeType presents the biggest challenge when converting and performing calculations.
The problems stem from the fact that by default the Rules use a Joda DateTime class to represent time, most notably `now`.
However, DateTimeType is not a Joda DateTime and in fact the two are incompatible, requiring some conversion in order to use the two together.
The lowest common denominator when working with time is to get at the epoch value.
Epoch is the number of milliseconds that has passed since 1 January 1970 GMT and stored in a `long`.
With epoch, one can compare two dates together, convert a Joda DateTime to a DateTimeType and visa versa.
A Number Items carries either a **DecimalType** or a **QuantityType** in case the Number Item has a dimension attached (e.g. `Number:Temperature` in the items file).
In rules, units are added to a number by a `|`, where the unit has to be put in quotes, if it contains non-alphabetic characters, e.g. `10|m`, but `20|"km/h"`.
A couple of commonly used units do not necessarily require quotes, these are `°C`, `°F`, `Ω`, `°`, `%`, `m²` and `m³`, so it is ok to write `20|"°C"`, but `20|°C` will also work.
The full explanation is [beyond the scope of this introduction](https://community.openhab.org/t/ambiguous-feature-call-whats-wrong-designer-user-or-bug/9477/4).
To avoid an error mentioning an "Ambiguous Method Call" always cast the state of a DecimalType to a Number, not DecimalType.
##### Player Item
The Player item allows to control players (e.g. audio players) with commands such as Play, Pause, Next, Previous, Rewind and Fastforward.
The Player Item carries three types with predefined commands
State Type | Commands
------------------|------------------
**PlayPauseType** | PLAY, PAUSE
**RewindFastforwardType** | REWIND, FASTFORWARD
**NextPreviousType** | NEXT, PREVIOUS
These types can be convert from Open and Closed to 1 and 0 with code similar to the Contact Item (OpenClosedType)
```java
//Loading from an Item
val int Playing = if (MyPlayerItem.state == PLAY) 1 else 0
```
##### PointType
See Location item
##### Rollershutter Item
See Dimmer
In addition to the command types of the item type Dimmer, the Rollershutter item accepts the StopMoveType with the commands STOP and MOVE
##### String Item
To convert the state of an Item that carries a StringType, the method toString can be invoked.
```java
//Loading from an Item
val stateAsString = MyStringItem.state.toString
```
In case an item returns a string containing a value as a hexadecimal number, it can be converted to an integer by using
```
//Loading hexvalue from string
val itemvalue = new java.math.BigDecimal(Integer::parseInt(myHexValue, 16))
```
##### Switch Item
A Switch Item carries a OnOffType.
OnOffType is an Enumeration.
One can convert from ON and OFF to 1 and 0 with code similar to:
```java
val SwitchNum = if (MySwitchItem.state == ON) 1 else 0
```
#### Deeper Dive
While interacting with Item states, care must be taken to understand the difference between Objects and primitives.
As all object-oriented computer languages, Java and the Rules DSL have implemented the concept of inheritance.
However, inheritance only applies to Objects and does **not** apply to primitives; examples for primitives are `integer` and `boolean`.
Inheritance allows to take an existing Object type, called a Class, and adding to it to make it into something different.
This “something different” becomes a Child of the original Class, the parent. The Child still can do everything the parent could do.
The top level base Class for all Objects in Java and the Rules DSL is called simply `Object`.
In addition to other useful things, the class `Object` implements a method called `toString`.
And since `Object` is the parent of all Objects, ALL Classes also implement a `toString` method.
_However primitives do not inherit from Object.
They don't inherit from anything and they don't have any methods at all which includes the lack of a toString Method._
Objects are typically equipped with many more type conversion methods, while primitives do not support any type conversion.
This distinction is very relevant when trying to use the result of a calculation and apply it to an Item state.
The `sendCommand` is a generic action and needs to be able to work with all Item types.
Actions only support two String arguments as all Objects will support the conversion `toString`.
`sendCommand (MyItem, new_state)` will automatically use the `MyItem.toString` method to convert MyItem into a String.
It will also attempt to do so with the second argument if `new_state` is not already a String.
However, if the second argument is a primitive, and not an Object, it does not carry a method `toString`.
Thus, Rules DSL will not be able to cast `new_state` as a String.
As a consequence, the use of `sendCommand(MyItem, primitive)`, using a primitive as the second argument, will almost always fail.
The different syntax for the generic and the objective-specific differs and is given in the table below:
The benefit of using Objects over primitives is apparent through the following type conversions that are automatically invoked by Object as the context requires.
Using the method `MyItems.sendCommand()` that is owned by MyItem will use the `sendCommand` method that is suitable to make the necessary type conversions.
For example, the `NumberItem` class would have a `sendCommand(int)`, `sendCommand(long)`, `sendCommand(float)`, `sendCommand(double)`, `sendCommand(Number)`, `sendCommand(DecimalType)`, and `sendCommand(String)` method.
Each of these separate methods is individually written to handle all of these different types of Objects.
MyItem will automatically apply the method that corresponds to the argument type.
Besides the implicitly available variables for items and commands/states, rules can have additional pre-defined variables, depending on their triggers:
The `transform` method tries to transform the given value and if it does not succeed it returns the original unchanged value.
In contrast to the `transform` method, the `transformRaw` method does not catch any `TransformationException`s internally, but throws them, so that the caller can handle it.
