Chapter 8.2 – Automation (Events) in the DOMIQ System Configurator

The Events tab is used to define logical rules to be carried out by the Base module. You can think of them as a kind of macro that defines the system’s behavior rules in response to conditions that have occurred. For the rest of this chapter, we’ll refer to them as events. Understanding the concepts presented here well is key, so if something seems unclear, spend more time on it — it’ll be time well invested.
You can think of events this way: JEŻELI TO, WTEDY ZRÓB TAMTO.
The first part of the expression — JEŻELI TO — represents the cause, i.e. something happened in the system that it’s supposed to react to in a certain way. In this part of the event’s definition, you can also specify additional conditions that must be met for the event to move into the action-execution phase.
The second part of the expression — WTEDY ZRÓB TAMTO — is the definition of the actions to be carried out by the DOMIQ system in response to the event occurring.
Study the examples below, which describe the concept in words:

1. If the motion sensor in the hallway is triggered –> turn on the hallway lights.
2. The example above, but extended with an additional condition:
   If the motion sensor in the hallway is triggered and it’s after dark ->turn on the hallway lights.
3. Another version of the first example:
   If the motion sensor in the hallway is triggered and the alarm is armed -> Turn on all the lights, send a notification to mobile devices, start recording on the cameras.
   

The Events tab is divided into three sections:

1. Button bar;
2. Structure;
3. Details;
4. Actions;
   

1. Button Bar #

At the top of the window, there is a bar with buttons.

1. + Event – Click to add a new event.
2. + Group – Click to add a new event group.
3. Copy – Copies the currently selected element (an event or a group) to the clipboard.
4. Paste – Pastes the contents of the clipboard.
5. Delete – Click to delete the selected elements.
6. Import – Allows importing an .xml configuration file.
7. Export – Lets you save the current list of events to an .xml file.
8. Export selected – Lets you save to a file only the elements whose checkbox is checked. It’s common to duplicate a given piece of functionality across multiple installations. This way, you can export just part of the events and use them in another location.
9. Save – Saves the current configuration in the memory of the Base module.
10. Restore – Loads the last saved configuration into the structure tree.

2. Structure #

The Structure window displays the list of events. The list has a hierarchical layout, similar to the Remote tab.

1. To add new elements, use the + Event or + Group buttons. If you want to add an element inside a group, select it from the list, then use the + Event or + Group buttons.
   
2. To change an element’s position in the structure, drag the selected element and drop it in a new location. This is also how you can add individual events to groups.
   
3. If an element cannot be added in the selected place, you will see a red indicator. For correct operations, the indicator is green.
4. The structure tree follows these rules regarding element hierarchy:
   
   • Both types of elements can be added at the top level.
   • Both types of elements can be added inside a Group.
   • Events cannot have nested elements.
     
5. To change the properties of a selected element, click on it – its attributes will be displayed in the Details window, and Actions (events only).
   
6. To delete element(s), select them by clicking the checkbox on the right side of the label, and then click the Delete button or the Backspace key on the keyboard. If the interface element being deleted has nested elements, they will also be deleted.
7. To copy an element, click on it (a light blue rectangle indicator will appear on the right side of the label), and then click the Copy button or the Ctrl + C key combination. The element has been copied and is in the clipboard.
8. To paste the copied element, use the Paste button or the keyboard shortcut Ctrl+V. The copied element will be placed in the following location:
   
   • below the currently selected element;
   • at the end of the list, if a Group-type element is selected.
     
9. The search field lets you quickly find elements in the structure. You can search based on: the description, the content of the Channel field, or the element type. Typing E.IDS.input in the search bar, for example, will display all controls that contain that content in the Channel field.
   
10. The Select All checkbox allows for quick selection of all elements in the structure. This is particularly useful when you want to quickly delete the entire structure.

2.1. Group #

A Group is used to combine into sets events that perform related functionality — for example, events related to the alarm system, or events related to ventilation, etc. This makes it easier to keep the event structure organized.

A Group can have execution conditions assigned to it. These form a logical AND with the conditions of the individual events. However, the conditions assigned to a group have higher priority — they are checked first. If they aren’t met, no event inside the group will be triggered.

2.2. Event #

A single logical rule.

3.Details #

This table is used to define the attributes of events and groups. At this stage, we return to the concept described earlier: JEŻELI TO, WTEDY ZRÓB TAMTO. The Details window is used to define the first part of the expression, i.e. JEŻELI TO.

• Active – Uncheck to deactivate the event. Inactive elements are displayed in the structure tree with a struck-through label. This field is checked by default.
• Description – Enter a brief description of the event/group here. Optional field.
• Channel (events only) – IMPORTANT! Note the orange background color of the Channel field and the note
  “Requires the C. or E. prefix.”
  What are the C. and E. prefixes?
  The C. prefix (command) should be understood as “in response to a command.” The E. prefix (event), on the other hand, means “in response to a change in an identifier’s value (state).” This is an important distinction, since not all commands result in a change in state. So, in the Channel field, you should enter the name of the identifier whose state change is to be observed, or to which a command has been sent.

An example best illustrates this:

1. Channel: C.IDS.armed.1
   Data: 1
   A command to arm zone No. 1 in the alarm system has been received. The Base module can react to this with any sequence of actions, and they may be executed even before the alarm zone is actually armed.
2. Channel: E.IDS.armed.1
   Data: 1
   Alarm zone No. [1] has been armed — a fact already accomplished, the zone’s state has changed. The Base module can react to this state change with any sequence of actions, e.g. turning off lights left on in the house, lowering the heating temperature, etc.

You can also use match patterns in the Channel field to create more advanced event definitions. You can read more about this in the Patterns section later in this chapter.

1. Data – In this field, enter the value (of a command or a state update) that the system should react to. The examples below illustrate this:
   • The system should react to a relay being turned on — it then takes the value 1
     Data: 1
   • The system should react to a temperature of 23°C being reached
     Data: 23

If the Data field is left empty, the event will be triggered by any value. Additionally, in the Data field, you can reference the value of another identifier using identifier binding — this is described in the Identifier Binding section.

• Condition – Lets you define an additional condition that must be met for the event to be executed. The condition forms a logical AND with the basic condition contained in the Data field. The basic form of a condition is a comparison of an identifier’s current state with a specific value, following the notation: <nazwa_identyfikatora><operator><wartość>. If the identifier’s value is a string, e.g. “dark,” the value must be enclosed in quotation marks. There can be several additional conditions, making it possible to create more complex logical rules that determine whether the event is executed. Keep in mind, however, that commands preceded by a condition will be executed if, and only if, the conditional expression is satisfied.

The Condition field allows the use of the following operators:

Keep in mind that a logical AND (and) takes precedence over a logical OR (or). For more complex cases where and and or are used together, we recommend using parentheses to separate smaller fragments of the conditional statement, to avoid any mistakes in the order in which the expressions are evaluated (see the examples below).

Basic examples

1. IDS.armed.1==1
   Only when zone one is armed.
2. IDS.entry.1==1 and VAR.pora=='lato'
Only when the entry delay for zone 1 is set, and the variable VAR.pora has the value “lato” (summer).
3. MEM.godzina>20 or VAR.pora=='ciemno'
Only when the value of the variable MEM.godzina is greater than 20, or the variable VAR.pora has the value “ciemno” (dark).
4. EXP.output.3.1~=1
Only when relay No. 1 in the Satel block at address 3 is not on.

Precedence in conditions and compound expressions

1. zmienna3==1 or zmienna2==0 and zmienna1==1
   The logical AND will be evaluated first, followed by the logical OR.
2. zmienna3==1 or zmienna2==0 and and zmienna1==1
   Adding parentheses to the previous example completely changes the meaning of the condition. The expression in parentheses is evaluated first, followed by the logical AND.
3. (zzmienna1==1 and zmienna2==2)or (zmienna3==3 and zmienna4==4)
   This is an example of an OR of ANDs. The expressions in parentheses (the ANDs) are evaluated first, followed by the logical OR. An AND of ORs can be created in an analogous way, and so on.

In the Condition field, you can also use the age function, which returns the time, expressed in seconds, since a given identifier’s last change. This lets an event be executed with a specific delay relative to the last change of any identifier in the system.

1. age(‘MODBUS.int.vent.temp’) > 60
   This condition should be understood as: “execute when the last change to the value of the identifier MODBUS.int.vent.temp was at least 60 seconds ago.”

Additionally, the Condition field lets you declare expressions using patterns (see Patterns) and identifier binding (see Identifier Binding below). This makes it possible to build very complex rules, which is what makes events such an important part of building automation.

4. Actions #

The Actions window is used to define the list of tasks the Base module should carry out as a result of an event being triggered. A description of this interface can be found in subsection: 8.1. Actions

1. Using an alarm control panel’s PIR sensors to turn on lights.
   Let’s assume the sensor is connected to binary input No. 1 on the Satel INT-IORS module at address 1, and the lighting is connected to relay No. 3 on the same module. Everything is controlled via the DOMIQ/Expander module.
   
   • Channel: E.EXP.input.1.1
   • Data: 1
   • +Command
   • Name: C.EXP.output.1.3
   • Data: 1
2. Automatically raising a blind when a window is opened. Let’s assume the window-opening sensor is connected to the Satel alarm control panel, input No. 10, and the blind is connected to a Shelly 2.5 module named rolety_salon
   • Channel: E.IDS.input.10
   • Data: 1
   • +Command
   • Name: C.SHELLY.rolety_salon.roller.0
   • Value: up

5. Advanced Topics
#

5.1. Identifier Binding #

This is a feature that simplifies the creation of complex logical rules. It lets you reference, within an event’s definition, the current value of any identifier. To do this, enclose the identifier’s name in curly braces, e.g.{LCN.output.0.10.1}. When you use this notation, the Base module will automatically retrieve the current value of the specified identifier at the moment the given rule is triggered.
You can use identifier binding in the Data fields in the Details window, and in the Value field in the + Command window. Additionally, identifier binding is available in the Condition field, but there — unusually — it does not require the use of curly braces.

Study the examples below:

1. Executing a command based on a value selected by the user in the Remote app.
   Let’s assume a situation where, in response to an event, a certain command is to be executed. However, the command’s value should depend on the option selected by the user in the Remote app. An example could be setting the heating’s target temperature (in this example, an LCN regulator) as a result of the alarm being armed (which could mean leaving the house). This is especially useful when the user wants to always be able to change this temperature in the future, without reconfiguring the system.
   The user’s choice is stored, for example, in a MEM variable. For the purposes of this example, we’ll call it MEM.userChoice. In that case, the event could have the following definition:
   Channel: E.IDS.armed.1
   Data: 1
   In the Actions section -> + Command
   Name: C.LCN.regulator.0.10.1
   Value: {MEM.userChoice}
2. Saving the date and time an alarm event occurred in the Satel system to a non-volatile MEM variable.
   Channel: E.IDS.alarm.1
   Data: 1
   In the Actions section -> + Command
   Name: C.MEM.lastAlarm
   Value: {CLOCK.datetime}
   When the event occurs, the Base module will retrieve the current value of the CLOCK.datetime identifier, which stores the date and time, and save it to the MEM.lastAlarm variable.
   MEM.lastAlarm.

5.2. Arithmetic #

The Base module lets you perform arithmetic operations on identifier values. The following operations are available: addition, subtraction, multiplication, division, exponentiation (^), and modulo division (%). Arithmetic is available in the Data fields (events) and the Condition field (events and timers).

1. Using arithmetic operations in the Condition field to control heating with hysteresis.
   For the purposes of this example, let’s assume: the target temperature is stored in a MEM variable named MEM.temp.salon. The measured temperature, meanwhile, is available in the identifier MODBUS.int.sensor.temp. When the measured temperature goes outside the established range, this should switch the relay controlling the heating loop’s valve. Let’s assume the measured temperature’s deviation can be at most 1.5°C. The relay controlling the valve is connected to a Satel INT-IORS block, controlled by the DOMIQ/Expander module. The block has address 1, and the relay is No. 3.
   • Temperature too low
     • Channel: E.MODBUS.int.sensor.temp
     • Data: Leave this blank, so the event is triggered on every change in the room’s temperature.
     • Condition: MODBUS.int.sensor.temp – 1,5 <= MEM.temp.salon IMPORTANT! This is simultaneously an example of identifier binding and arithmetic operations in the Condition field.
       In the Actions section -> + Command
     • Name: C.EXP.output.1.3
     • Value: 1
     • You can carry out an analogous action for a temperature that is too high, by simply changing the operator in the condition to >= and the command’s value to 0.

Using arithmetic operations in the Data field is closely tied to identifier binding. This lets you create more flexible event definitions, which will be triggered depending on the state of another identifier in the Base module. Remember to enclose the identifier’s name in curly braces in this case.
Arithmetic operations used in the Value field in the + Command window also require the use of curly braces. Arithmetic used here lets you dynamically modify a command’s value depending on the state of another identifier. This makes it possible, for example, to scale values.

1. Measured temperature compensation. Some temperature sensors require their readings to be compensated for, due to their mounting location. Let’s assume we want to compensate the readings of a sensor connected to the MODBUS bus by 2°C, and save the new, compensated value to a VAR variable named VAR.sensor.temp. Let’s assume the sensor’s identifier is: MODBUS.int.sensor.temp.
   Channel: E.MODBUS.int.sensor.temp
   Data: Leave this blank, so the event is triggered on every temperature change.
   +Command
   Name: C.VAR.sensor.temp
   Value: $D0 – 2
   The above should be understood as: take the value the event was triggered with, and subtract 2 from it. You can read more about using parameters in the Parameters section.

5.3. Patterns #

Patterns let you create very universal rules that can react to many events at once. This is a huge simplification of the configuration, saving a significant amount of time, and also an optimization from the point of view of the system’s operating performance. Patterns can only be used in the Channel field. You can use several patterns within a single event definition.

To understand the concept of patterns, consider the examples below:

1. Let’s assume a situation where the DOMIQ system should react with the same action to a trigger on any one of n motion sensors, where n is any number of sensors. Instead of creating an event for each sensor, you can create a single event using patterns that will catch all of these events! Let’s assume the sensors are connected to a Satel INT-IORS module at address 3, controlled via the DOMIQ/Expander module. In that case, the event would have the following definition:
   
   Channel: E.EXP.input.3.(%d)
   The event will be triggered for any binary input (1-8) that changes its value from 0 to 1.
   Data: 1
   In the Actions section, declare the commands.
2. The event will be triggered if any relay in the LCN module at address 10 is turned off.
   Channel: E.LCN.relay.0.10.(%d)
   Data: 0
3. The event will be triggered if any dimmable output in segment No. 10 is driven to 100%.
   Channel: E.LCN.output.10.(%d+).(%d)
   Data: 100
4. The event will be triggered if any alarm device changes its state — in response to state changes for identifiers of both the IDS.alarm.x and IDS.output.x
   IDS.output.x. …and so on
   Channel: E.IDS.(%a+).(%d+)
   Data: 1

5.4. Parameters #

Parameters are closely tied to patterns, since they capture the elements extracted by the patterns. You can use several parameters within a single event definition. For the contents of patterns to be passed to parameters, the pattern in the event’s definition must be enclosed in round parentheses. Parameters let you create very universal events (see the examples).
Parameters can be used in the Condition field, and in the Name and Value fields in the + Command editing window.

The $C0 parameter always stores the event’s full name, while $D0 stores its current value.
The $D0 parameter offers great possibilities, which is why it’s important to understand how to use it.

1. An event reacting to an observed value being exceeded, e.g. a room temperature being exceeded.
   For the purposes of this example, let’s assume we’re observing the temperature measured by a sensor connected to the MODBUS bus. Its identifier is MODBUS.int.sensor.temp. The event is meant to execute a specific list of actions when the temperature drops below 0°C.
   Channel: E.MODBUS.int.sensor.temp
   Data: Leave this field blank, so the event is triggered by every change in the measured temperature.
   Condition: $D0 < 0
   This condition should be understood as follows: if the value the event was triggered with is less than 0.
2. Turning on a relay depending on the state of a binary input.
   Without using patterns and parameters, this would require creating two events: one for a logical 1 on the binary input, and another for a logical 0. Using them, this can be achieved with a single event. Let’s assume we’re observing a state change on binary input No. 5, connected to a Satel INT-IORS module at address 2, controlled via the Expander module, and that the relay is No. 7 and is in the LCN module at address 10.
   Channel: E.EXP.input.2.5
   Data: Leave this field blank, so the event is triggered by both states of the binary input.
   +Command:
   Name: C.LCN.relay.0.10.7
   Value: $D0
   Using the $D0 parameter captures the binary input’s value (1 or 0) and passes that value to the relay.
3. The MEM variable will store information about the most recently triggered alarm sensor. For the purposes of this example, we’ll call itMEM.lastInput. This is an example showing the use of parameters in the Channel field.
   
   Channel: E.IDS.input.(%d+)
   Data: 1 +Command:
   Name: C.MEM.lastInput
   Value: $C1
   The pattern (%d+) means “one or more digits.” So it will capture both a single digit from 0-9, and a number, e.g. 123. The value captured by the pattern is then available in the parameter $C1. So, by referencing it in the command, we save the sensor’s number as the value of the MEM variable.
4. Sending a notification to the DOMIQ/Remote app.
   Channel: E.IDS.alarm.(%d+) — any alarm zone will be checked.
   Data: 1 +Command:
   Name: C.REMOTE.notify
   Value: Enter here the content of the notification that will be displayed on the device’s screen. For example, entering “Alarm in zone $C1” means that, in the event of an alarm, the user will see a message reading “Alarm in zone x,” where x is the number of the zone in which the alarm occurred.
5. Channel: E.LCN.output.0.10.(%d)
   Data: (%d+)
   Let’s assume dimmable output No. 2 in the LCN module at address 10 reaches a value of 50%. This generates the event E.LCN.output.0.10.2=50. In that case, the parameter$C1 is assigned the number of the output that changed state — in this case, 2 — while the parameter $D1 has the value 50.