Events Programming

The EVENTS programming environment is based on a simple language that associates one or more actions to a field event or combination of conditions.

Programming EVENTS is as simple as editing the events.txt file, located in the main directory. Compared to Java, there is no compilation process. When you save the file, it is automatically reloaded and becomes immediately effective.

An event is an expression that refers to the persistent status or transient event of devices, to conditions applied to local variables, and to various internal events. An action is a control command sent to a device, or several other internal functions, like setting variables and program timers.

Example:

IO k.33 = 1 : k.34 = 1

when the light actuator with data point name k.33 is turned on, HSYCO automatically turns on the actuator with data point name k.34.

Example:

DAY : IO k.33 k.34 k.35 k.36 = 0

at sunrise, the actuators named k.33, k.34, k.35 and k.36 are turned off.

In this chapter we will describe the general format of events.txt, and all the built-in events and actions.

The events.txt file is usually modified with the text editor in HSYCO’s File Manager. When you save the file, it is automatically checked and, if errors are found, a warning icon appears in the top bar.

Touch that icon to show the list of errors. Errors are also written in the log file. Lines containing errors are ignored.

You can also enable the editor’s syntax highlighter for improved readability.

The EVENTS Language

EVENTS uses the simple format:

event : actions

Several events can be combined together to implement complex expressions which represent the combination of different conditions.

The logical operators AND, OR, NOT and the round brackets are available to define the operations precedence.

If the brackets are not used, the AND and OR operations are executed from left to right. The NOT operator has priority and is executed on the first expression after it, before AND or OR conditions.

Example:

IO k.33 OR IO K.34

this event occurs any time the actuators 33 or 34 change their status.

Example:

CAMERA "entrance" AND NOT IO K.34 = 0

is an event that occurs when the camera “entrance” starts recording, but only if the K.34 datapoint is not 0.

Example:

IO k.33 > 5 OR IO K.34 = 0 AND IO K.35 = 0

is equivalent to

(IO k.33 > 5 OR IO K.34 = 0) AND IO K.35 = 0

Example:

NOT IO k.33 = 1 AND IO k.34 = 1

is equivalent to

(NOT IO k.33 = 1) AND IO k.34 = 1

Comments

Comments are vital to describe the functions, even if the EVENTS language is very easy to understand.

A comment is identified by the # character.

All characters following # will be ignored until the end of line, unless the # character is enclosed between double quotes.

Example:

# actions executed at sunset
NIGHT:
	IO k.33 k.34 k.35 k.36 = 1,	# garden lights on
	IO k.43 k.44 = UP,		# rise the awnings
	LOG = "# and this is not a comment"

Other General Rules

Keywords are case insensitive. Devices ids are also case insensitive. The EVENTS interpreter converts all ids to lower case, so it is recommended to use only lower case ids in hsyco.ini if you use EVENTS.

The built-in constant values (ON, OFF, UP, DOWN, STOP, FLIP, RECON, RECOFF, MERGE, UNMERGE, PLAY) can be written in capital letters or in lower case. All other custom values will retain the case.

Example:

IO k.43 = UP and IO k.44 = DOWN : CAMERA cam1 = 60

is equivalent to:

io k.43 = up AND io k.44 = down : camera cam1 = 60

Example:

IO k.36 = 1 : UISET message.text = "Stairs light ON"

The text “Stairs light ON” remains unchanged.

Spaces and not-relevant tabulation characters are ignored.

In some cases separation spaces are not necessary:

IO k.36=1 

is a valid expression, while

IOk.36 = 1 

is not valid because the keywords must be separated by their attributes.

The EVENTS interpreter tries to understand strings even when not enclosed in double quotes, but we consider a good practice to always use double quotes to delimit text strings, and this may even become mandatory in future releases.

Example:

IO k.36 = 1 : LOG = "I turn on the light: 36"

Stable and transient events

IO k.33

is a transient event. It occurs only during the status change of the actuator with data point name k.33. If it is part of a complex expression, it will be true only when the expression evaluation is triggered by that specific change event, and will be false when the expression evaluation is triggered by any other event. For example:

IO k.33 AND IO k.33

is an event that will never occur, because two transient events can never be simultaneously true.

A stable event is value based condition. For example:

IO k.33 > 40

is a stable event. It occurs when the status value of actuator k.33 is greater than 40 (more than 40% of a dimmer level).

Unlike the transient events, this expression is true anyway, even after the transient event, so:

IO k.33 > 40 AND IO k.34 > 40

is an event that may occur when both the actuators k.33 and k.34 are on with a level greater than 40%.

In some cases it would be necessary to use a transient event associated to a device, also combined with status expressions of the device itself.

Example:

IO k.33 = 1 AND IO k.34 = 1 AND NOT IO k.33

The expression NOT IO k.33 excludes the events generated from any status change of device k.33. Meanwhile IO k.33 = 1 makes the expression true only when the device status is ON.

As a result, this event occurs when the devices k.33 and k.34 are simultaneously ON, but only on the status change of device k.34, and ignoring the status change of device k.33.

Example:

IO k.33 = 1 AND IO k.34 = 1 AND NOT IO k.33 :
	IO k.33 = 0, WAIT = 0.5, IO k.33 = 1

If light k.33 is already ON, as soon as light k.34 is turned on, light k.33 will flash once.

By omitting the expression NOT IO k.33 the light wouldn’t stop blinking because the action would trigger the same event again and again.

One Event, More Rules

You can define several rules referencing the same event.

When HSYCO detects any status change in the system, it scans EVENTS for all event expressions that could be affected by that event. All relevant expression are then evaluated and, if true, the associated lists of actions are executed.

This process is normally performed top-down on the events.txt file, but the execution order is not guaranteed.

Example:

IO k.34 = 1 : IO k.36 = 0
IO k.34 = 1 AND DAY : IO k.37 = 0

When the actuator k.34 is turned on, these rules cause actuator k.36 to go off, while the actuator k.37 will be turned off only during the day.

Actions

You can associate multiple, comma separated actions to each event. For example:

NIGHT : IO k.33 = 1, IO k.34 = 1, IO k.88 = UP

In order to speed up the writing and make rules clearer, many commands let you specify a list of addresses as attributes of the command. The rule written above can be rewritten in a shorter form as:

NIGHT : IO k.33 k.34 = 1, IO k.88 = UP

Each event : action rule is normally written on a single line. However the readability can be improved by typing the list of actions on following lines, after adding a comma at the end of the preceding lines. It Is also possible to write only the event expression on the first line, followed by : and start the list of actions in the following line:

NIGHT :
	IO k.33 k.34 = 1, IO k.86 k.87 k.88 = UP

The event expression can’t be written on more than one line.